pagekit-core 0.1.0__tar.gz

pagekit_core-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.turbo/
+.env
+.env.local
+*.log
+.DS_Store
+coverage/
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/

pagekit_core-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: pagekit-core
+Version: 0.1.0
+Summary: Python client for the Pagekit content API
+Project-URL: Homepage, https://github.com/arovi-labs/pagekit
+Project-URL: Repository, https://github.com/arovi-labs/pagekit
+Project-URL: Issues, https://github.com/arovi-labs/pagekit/issues
+Author: Arovi Labs
+License-Expression: MIT
+Keywords: blog,cms,content-api,headless,pagekit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pagekit
+
+Python client for the [Pagekit](https://pagekit.app) content API.
+
+## Installation
+
+```bash
+pip install pagekit-core
+```
+
+## Quick start
+
+```python
+from pagekit import Pagekit
+
+client = Pagekit(api_key="pk_live_...")
+
+# List posts
+page = client.posts.list(status="published", limit=10)
+for post in page.data:
+    print(post.title)
+
+# Create a post
+post = client.posts.create(title="Hello world", content="<p>First post</p>")
+
+# Get by slug
+post = client.posts.get_by_slug("hello-world")
+```
+
+## Async usage
+
+```python
+from pagekit import AsyncPagekit
+
+client = AsyncPagekit(api_key="pk_live_...")
+
+posts = await client.posts.list()
+```
+
+## Configuration
+
+```python
+client = Pagekit(
+    api_key="pk_live_...",
+    base_url="https://api.pagekit.app/v1",  # default
+    timeout=30,                               # seconds
+    headers={"X-Custom": "value"},            # extra headers
+)
+```
+
+## Error handling
+
+```python
+from pagekit import Pagekit, PagekitError
+
+client = Pagekit(api_key="pk_live_...")
+
+try:
+    post = client.posts.get("nonexistent")
+except PagekitError as e:
+    print(e.status)   # 404
+    print(e.code)     # "not_found"
+    print(e.is_auth_error)      # False
+    print(e.is_rate_limited)    # False
+    print(e.is_server_error)    # False
+```
+
+## License
+
+MIT

pagekit_core-0.1.0/README.md

@@ -0,0 +1,70 @@
+# pagekit
+
+Python client for the [Pagekit](https://pagekit.app) content API.
+
+## Installation
+
+```bash
+pip install pagekit-core
+```
+
+## Quick start
+
+```python
+from pagekit import Pagekit
+
+client = Pagekit(api_key="pk_live_...")
+
+# List posts
+page = client.posts.list(status="published", limit=10)
+for post in page.data:
+    print(post.title)
+
+# Create a post
+post = client.posts.create(title="Hello world", content="<p>First post</p>")
+
+# Get by slug
+post = client.posts.get_by_slug("hello-world")
+```
+
+## Async usage
+
+```python
+from pagekit import AsyncPagekit
+
+client = AsyncPagekit(api_key="pk_live_...")
+
+posts = await client.posts.list()
+```
+
+## Configuration
+
+```python
+client = Pagekit(
+    api_key="pk_live_...",
+    base_url="https://api.pagekit.app/v1",  # default
+    timeout=30,                               # seconds
+    headers={"X-Custom": "value"},            # extra headers
+)
+```
+
+## Error handling
+
+```python
+from pagekit import Pagekit, PagekitError
+
+client = Pagekit(api_key="pk_live_...")
+
+try:
+    post = client.posts.get("nonexistent")
+except PagekitError as e:
+    print(e.status)   # 404
+    print(e.code)     # "not_found"
+    print(e.is_auth_error)      # False
+    print(e.is_rate_limited)    # False
+    print(e.is_server_error)    # False
+```
+
+## License
+
+MIT

pagekit_core-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pagekit-core"
+version = "0.1.0"
+description = "Python client for the Pagekit content API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Arovi Labs" }]
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["pagekit", "cms", "headless", "content-api", "blog"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/arovi-labs/pagekit"
+Repository = "https://github.com/arovi-labs/pagekit"
+Issues = "https://github.com/arovi-labs/pagekit/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.22"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pagekit"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pagekit_core-0.1.0/src/pagekit/__init__.py

@@ -0,0 +1,46 @@
+from .client import AsyncPagekit, Pagekit
+from .errors import PagekitError
+from .http import DEFAULT_BASE_URL
+from .types import (
+    Author,
+    AuthorListParams,
+    Category,
+    CategoryListParams,
+    Media,
+    MediaCreateInput,
+    MediaListParams,
+    Paginated,
+    Pagination,
+    Post,
+    PostCreateInput,
+    PostListParams,
+    PostStatus,
+    PostUpdateInput,
+    Seo,
+    Tag,
+    TagListParams,
+)
+
+__all__ = [
+    "AsyncPagekit",
+    "DEFAULT_BASE_URL",
+    "Pagekit",
+    "PagekitError",
+    "Author",
+    "AuthorListParams",
+    "Category",
+    "CategoryListParams",
+    "Media",
+    "MediaCreateInput",
+    "MediaListParams",
+    "Paginated",
+    "Pagination",
+    "Post",
+    "PostCreateInput",
+    "PostListParams",
+    "PostStatus",
+    "PostUpdateInput",
+    "Seo",
+    "Tag",
+    "TagListParams",
+]

pagekit_core-0.1.0/src/pagekit/client.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import httpx
+
+from .errors import PagekitError
+from .http import DEFAULT_BASE_URL, AsyncHttpClient, SyncHttpClient
+from .resources.authors import AsyncAuthorsResource, SyncAuthorsResource
+from .resources.categories import AsyncCategoriesResource, SyncCategoriesResource
+from .resources.media import AsyncMediaResource, SyncMediaResource
+from .resources.posts import AsyncPostsResource, SyncPostsResource
+from .resources.tags import AsyncTagsResource, SyncTagsResource
+
+
+class AsyncPagekit:
+    """Async Pagekit content API client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            http_client=http_client,
+        )
+        self.posts = AsyncPostsResource(self._http)
+        self.authors = AsyncAuthorsResource(self._http)
+        self.categories = AsyncCategoriesResource(self._http)
+        self.tags = AsyncTagsResource(self._http)
+        self.media = AsyncMediaResource(self._http)
+
+    async def close(self) -> None:
+        await self._http._client.aclose()
+
+    async def __aenter__(self) -> AsyncPagekit:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+
+class Pagekit:
+    """Synchronous Pagekit content API client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._http = SyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            http_client=http_client,
+        )
+        self.posts = SyncPostsResource(self._http)
+        self.authors = SyncAuthorsResource(self._http)
+        self.categories = SyncCategoriesResource(self._http)
+        self.tags = SyncTagsResource(self._http)
+        self.media = SyncMediaResource(self._http)
+
+    def close(self) -> None:
+        self._http._client.close()
+
+    def __enter__(self) -> Pagekit:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

pagekit_core-0.1.0/src/pagekit/errors.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class PagekitError(Exception):
+    """Error returned by the Pagekit API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "api_error",
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+
+    @property
+    def is_auth_error(self) -> bool:
+        return self.status in (401, 403)
+
+    @property
+    def is_rate_limited(self) -> bool:
+        return self.status == 429
+
+    @property
+    def is_server_error(self) -> bool:
+        return self.status >= 500

pagekit_core-0.1.0/src/pagekit/http.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import httpx
+
+from .errors import PagekitError
+
+DEFAULT_BASE_URL = "https://api.pagekit.app/v1"
+
+
+class HttpClient(Protocol):
+    async def request(
+        self, path: str, *, method: str = "GET", query: dict[str, Any] | None = None, body: Any = None
+    ) -> Any: ...
+
+
+def _to_camel(key: str) -> str:
+    parts = key.split("_")
+    return parts[0] + "".join(w.capitalize() for w in parts[1:])
+
+
+def _serialize_params(obj: Any) -> Any:
+    if hasattr(obj, "__dataclass_fields__"):
+        result = {}
+        for k, v in obj.__dataclass_fields__.items():  # type: ignore[attr-defined]
+            val = getattr(obj, k)
+            if val is not None:
+                result[_to_camel(k)] = _serialize_params(val)
+        return result
+    if isinstance(obj, dict):
+        return {k: _serialize_params(v) for k, v in obj.items() if v is not None}
+    if isinstance(obj, list):
+        return [_serialize_params(v) for v in obj]
+    if hasattr(obj, "value"):
+        return obj.value
+    return obj
+
+
+def _build_query(params: Any) -> dict[str, str]:
+    if params is None:
+        return {}
+    raw = _serialize_params(params) if hasattr(params, "__dataclass_fields__") else params or {}
+    return {k: str(v) for k, v in raw.items() if v is not None and v != ""}
+
+
+def _unwrap_type(ft: Any) -> Any:
+    """Unwrap Optional/Union types to get the inner dataclass type."""
+    import typing
+
+    origin = getattr(ft, "__origin__", None)
+    if origin is typing.Union:
+        args = [a for a in ft.__args__ if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return ft
+
+
+def _deserialize(data: dict[str, Any], cls: type) -> Any:
+    if not isinstance(data, dict):
+        return data
+    import dataclasses
+
+    if not dataclasses.is_dataclass(cls):
+        return data
+
+    field_map = {f.name: f for f in dataclasses.fields(cls)}
+    kwargs = {}
+    for f in dataclasses.fields(cls):
+        snake = f.name
+        camel = _to_camel(snake)
+        raw = data.get(camel, data.get(snake))
+        if raw is None:
+            continue
+        ft = f.type
+        if isinstance(ft, str):
+            import typing
+
+            ft = typing.get_type_hints(cls).get(snake, f.type)
+        inner = _unwrap_type(ft)
+        if dataclasses.is_dataclass(inner) and isinstance(raw, dict):
+            kwargs[snake] = _deserialize(raw, inner)
+        else:
+            kwargs[snake] = raw
+    return cls(**kwargs)
+
+
+def _extract_message(body: Any) -> str:
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict) and "message" in err:
+            return err["message"]
+        if "message" in body:
+            return body["message"]
+    return "Unknown error"
+
+
+def _extract_code(body: Any) -> str:
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict) and "code" in err:
+            return err["code"]
+        if "code" in body:
+            return body["code"]
+    return "api_error"
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key:
+            raise PagekitError("api_key is required", code="missing_api_key")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._default_headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            **(headers or {}),
+        }
+        self._client = http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+        )
+
+    async def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = {**self._default_headers}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            resp = await self._client.request(
+                method,
+                url,
+                headers=headers,
+                params=_build_query(query) or None,
+                content=__import__("json").dumps(_serialize_params(body)) if body is not None else None,
+            )
+        except httpx.TimeoutException:
+            raise PagekitError("Request timed out", code="timeout")
+        except httpx.HTTPError as exc:
+            raise PagekitError(f"Network error: {exc}", code="network_error")
+
+        if resp.status_code == 204:
+            return None
+
+        try:
+            data = resp.json()
+        except Exception:
+            data = None
+
+        if not resp.is_success:
+            raise PagekitError(
+                _extract_message(data),
+                status=resp.status_code,
+                code=_extract_code(data),
+                details=data,
+            )
+
+        return data
+
+
+class SyncHttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise PagekitError("api_key is required", code="missing_api_key")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._default_headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            **(headers or {}),
+        }
+        self._client = http_client or httpx.Client(
+            timeout=httpx.Timeout(timeout),
+        )
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = {**self._default_headers}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            resp = self._client.request(
+                method,
+                url,
+                headers=headers,
+                params=_build_query(query) or None,
+                content=__import__("json").dumps(_serialize_params(body)) if body is not None else None,
+            )
+        except httpx.TimeoutException:
+            raise PagekitError("Request timed out", code="timeout")
+        except httpx.HTTPError as exc:
+            raise PagekitError(f"Network error: {exc}", code="network_error")
+
+        if resp.status_code == 204:
+            return None
+
+        try:
+            data = resp.json()
+        except Exception:
+            data = None
+
+        if not resp.is_success:
+            raise PagekitError(
+                _extract_message(data),
+                status=resp.status_code,
+                code=_extract_code(data),
+                details=data,
+            )
+
+        return data

pagekit_core-0.1.0/src/pagekit/resources/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from ..resources.authors import AsyncAuthorsResource, SyncAuthorsResource
+from ..resources.categories import AsyncCategoriesResource, SyncCategoriesResource
+from ..resources.media import AsyncMediaResource, SyncMediaResource
+from ..resources.posts import AsyncPostsResource, SyncPostsResource
+from ..resources.tags import AsyncTagsResource, SyncTagsResource
+
+__all__ = [
+    "AsyncAuthorsResource",
+    "AsyncCategoriesResource",
+    "AsyncMediaResource",
+    "AsyncPostsResource",
+    "AsyncTagsResource",
+    "SyncAuthorsResource",
+    "SyncCategoriesResource",
+    "SyncMediaResource",
+    "SyncPostsResource",
+    "SyncTagsResource",
+]

pagekit_core-0.1.0/src/pagekit/resources/authors.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ..http import AsyncHttpClient, SyncHttpClient, _build_query, _deserialize
+from ..types import Author, AuthorListParams, Paginated, Pagination
+
+
+class AsyncAuthorsResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: AuthorListParams | None = None) -> Paginated[Author]:
+        query = _build_query(params) if params else {}
+        raw = await self._http.request("/authors", query=query)
+        return Paginated(
+            data=[_deserialize(a, Author) for a in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    async def get(self, id: str) -> Author:
+        raw = await self._http.request(f"/authors/{quote(id, safe='')}")
+        return _deserialize(raw, Author)
+
+
+class SyncAuthorsResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self, params: AuthorListParams | None = None) -> Paginated[Author]:
+        query = _build_query(params) if params else {}
+        raw = self._http.request("/authors", query=query)
+        return Paginated(
+            data=[_deserialize(a, Author) for a in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    def get(self, id: str) -> Author:
+        raw = self._http.request(f"/authors/{quote(id, safe='')}")
+        return _deserialize(raw, Author)

pagekit_core-0.1.0/src/pagekit/resources/categories.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ..http import AsyncHttpClient, SyncHttpClient, _build_query, _deserialize
+from ..types import Category, CategoryListParams, Paginated, Pagination
+
+
+class AsyncCategoriesResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: CategoryListParams | None = None) -> Paginated[Category]:
+        query = _build_query(params) if params else {}
+        raw = await self._http.request("/categories", query=query)
+        return Paginated(
+            data=[_deserialize(c, Category) for c in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    async def get_by_slug(self, slug: str) -> Category:
+        raw = await self._http.request(f"/categories/{quote(slug, safe='')}")
+        return _deserialize(raw, Category)
+
+
+class SyncCategoriesResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self, params: CategoryListParams | None = None) -> Paginated[Category]:
+        query = _build_query(params) if params else {}
+        raw = self._http.request("/categories", query=query)
+        return Paginated(
+            data=[_deserialize(c, Category) for c in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    def get_by_slug(self, slug: str) -> Category:
+        raw = self._http.request(f"/categories/{quote(slug, safe='')}")
+        return _deserialize(raw, Category)

pagekit_core-0.1.0/src/pagekit/resources/media.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ..http import AsyncHttpClient, SyncHttpClient, _build_query, _deserialize
+from ..types import Media, MediaCreateInput, MediaListParams, Paginated, Pagination
+
+
+class AsyncMediaResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: MediaListParams | None = None) -> Paginated[Media]:
+        query = _build_query(params) if params else {}
+        raw = await self._http.request("/media", query=query)
+        return Paginated(
+            data=[_deserialize(m, Media) for m in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    async def create(self, input: MediaCreateInput) -> Media:
+        raw = await self._http.request("/media", method="POST", body=input)
+        return _deserialize(raw, Media)
+
+    async def delete(self, id: str) -> None:
+        await self._http.request(f"/media/{quote(id, safe='')}", method="DELETE")
+
+
+class SyncMediaResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self, params: MediaListParams | None = None) -> Paginated[Media]:
+        query = _build_query(params) if params else {}
+        raw = self._http.request("/media", query=query)
+        return Paginated(
+            data=[_deserialize(m, Media) for m in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    def create(self, input: MediaCreateInput) -> Media:
+        raw = self._http.request("/media", method="POST", body=input)
+        return _deserialize(raw, Media)
+
+    def delete(self, id: str) -> None:
+        self._http.request(f"/media/{quote(id, safe='')}", method="DELETE")

pagekit_core-0.1.0/src/pagekit/resources/posts.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ..http import AsyncHttpClient, SyncHttpClient, _build_query, _deserialize
+from ..types import (
+    Author,
+    AuthorListParams,
+    Paginated,
+    Pagination,
+    Post,
+    PostCreateInput,
+    PostListParams,
+    PostUpdateInput,
+)
+
+
+class AsyncPostsResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: PostListParams | None = None) -> Paginated[Post]:
+        query = _build_query(params) if params else {}
+        raw = await self._http.request("/posts", query=query)
+        return Paginated(
+            data=[_deserialize(p, Post) for p in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    async def get(self, id: str) -> Post:
+        raw = await self._http.request(f"/posts/{quote(id, safe='')}")
+        return _deserialize(raw, Post)
+
+    async def get_by_slug(self, slug: str) -> Post:
+        raw = await self._http.request(f"/posts/slug/{quote(slug, safe='')}")
+        return _deserialize(raw, Post)
+
+    async def create(self, input: PostCreateInput) -> Post:
+        raw = await self._http.request("/posts", method="POST", body=input)
+        return _deserialize(raw, Post)
+
+    async def update(self, id: str, input: PostUpdateInput) -> Post:
+        raw = await self._http.request(f"/posts/{quote(id, safe='')}", method="PATCH", body=input)
+        return _deserialize(raw, Post)
+
+    async def delete(self, id: str) -> None:
+        await self._http.request(f"/posts/{quote(id, safe='')}", method="DELETE")
+
+
+class SyncPostsResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self, params: PostListParams | None = None) -> Paginated[Post]:
+        query = _build_query(params) if params else {}
+        raw = self._http.request("/posts", query=query)
+        return Paginated(
+            data=[_deserialize(p, Post) for p in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+    def get(self, id: str) -> Post:
+        raw = self._http.request(f"/posts/{quote(id, safe='')}")
+        return _deserialize(raw, Post)
+
+    def get_by_slug(self, slug: str) -> Post:
+        raw = self._http.request(f"/posts/slug/{quote(slug, safe='')}")
+        return _deserialize(raw, Post)
+
+    def create(self, input: PostCreateInput) -> Post:
+        raw = self._http.request("/posts", method="POST", body=input)
+        return _deserialize(raw, Post)
+
+    def update(self, id: str, input: PostUpdateInput) -> Post:
+        raw = self._http.request(f"/posts/{quote(id, safe='')}", method="PATCH", body=input)
+        return _deserialize(raw, Post)
+
+    def delete(self, id: str) -> None:
+        self._http.request(f"/posts/{quote(id, safe='')}", method="DELETE")

pagekit_core-0.1.0/src/pagekit/resources/tags.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from ..http import AsyncHttpClient, SyncHttpClient, _build_query, _deserialize
+from ..types import Paginated, Pagination, Tag, TagListParams
+
+
+class AsyncTagsResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: TagListParams | None = None) -> Paginated[Tag]:
+        query = _build_query(params) if params else {}
+        raw = await self._http.request("/tags", query=query)
+        return Paginated(
+            data=[_deserialize(t, Tag) for t in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )
+
+
+class SyncTagsResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self, params: TagListParams | None = None) -> Paginated[Tag]:
+        query = _build_query(params) if params else {}
+        raw = self._http.request("/tags", query=query)
+        return Paginated(
+            data=[_deserialize(t, Tag) for t in raw["data"]],
+            pagination=_deserialize(raw["pagination"], Pagination),
+        )

pagekit_core-0.1.0/src/pagekit/types.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Generic, Literal, TypeVar
+
+T = TypeVar("T")
+
+
+class PostStatus(str, Enum):
+    DRAFT = "draft"
+    SCHEDULED = "scheduled"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"
+
+
+@dataclass
+class Seo:
+    title: str | None = None
+    description: str | None = None
+    canonical_url: str | None = None
+    og_image: str | None = None
+
+
+@dataclass
+class Author:
+    id: str
+    name: str
+    email: str | None = None
+    bio: str | None = None
+    avatar_url: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+@dataclass
+class Category:
+    id: str
+    name: str
+    slug: str
+    description: str | None = None
+
+
+@dataclass
+class Tag:
+    id: str
+    name: str
+    slug: str
+
+
+@dataclass
+class Media:
+    id: str
+    url: str
+    filename: str
+    mime_type: str
+    size: int
+    width: int | None = None
+    height: int | None = None
+    alt: str | None = None
+    created_at: str | None = None
+
+
+@dataclass
+class AuthorRef:
+    id: str
+    name: str
+
+
+@dataclass
+class CategoryRef:
+    id: str
+    name: str
+    slug: str
+
+
+@dataclass
+class Post:
+    id: str
+    title: str
+    slug: str
+    content: str
+    excerpt: str | None = None
+    cover_image: str | None = None
+    status: PostStatus = PostStatus.DRAFT
+    published_at: str | None = None
+    scheduled_for: str | None = None
+    author: AuthorRef | None = None
+    category: CategoryRef | None = None
+    tags: list[str] = field(default_factory=list)
+    seo: Seo = field(default_factory=Seo)
+    created_at: str = ""
+    updated_at: str = ""
+
+
+@dataclass
+class Pagination:
+    page: int
+    limit: int
+    total: int
+    total_pages: int
+    has_next_page: bool
+    has_previous_page: bool
+
+
+@dataclass
+class Paginated(Generic[T]):
+    data: list[T]
+    pagination: Pagination
+
+
+@dataclass
+class PostCreateInput:
+    title: str
+    content: str | None = None
+    slug: str | None = None
+    excerpt: str | None = None
+    cover_image: str | None = None
+    status: PostStatus | None = None
+    author_id: str | None = None
+    category_id: str | None = None
+    tags: list[str] | None = None
+    seo_title: str | None = None
+    seo_description: str | None = None
+    canonical_url: str | None = None
+    og_image: str | None = None
+    published_at: str | None = None
+    scheduled_for: str | None = None
+
+
+@dataclass
+class PostUpdateInput:
+    title: str | None = None
+    content: str | None = None
+    slug: str | None = None
+    excerpt: str | None = None
+    cover_image: str | None = None
+    status: PostStatus | None = None
+    author_id: str | None = None
+    category_id: str | None = None
+    tags: list[str] | None = None
+    seo_title: str | None = None
+    seo_description: str | None = None
+    canonical_url: str | None = None
+    og_image: str | None = None
+    published_at: str | None = None
+    scheduled_for: str | None = None
+
+
+@dataclass
+class PostListParams:
+    status: PostStatus | None = None
+    category: str | None = None
+    tag: str | None = None
+    author: str | None = None
+    search: str | None = None
+    page: int | None = None
+    limit: int | None = None
+    sort: str | None = None
+
+
+@dataclass
+class CategoryListParams:
+    page: int | None = None
+    limit: int | None = None
+    sort: str | None = None
+
+
+@dataclass
+class TagListParams:
+    page: int | None = None
+    limit: int | None = None
+    sort: str | None = None
+
+
+@dataclass
+class AuthorListParams:
+    page: int | None = None
+    limit: int | None = None
+    sort: str | None = None
+
+
+@dataclass
+class MediaListParams:
+    page: int | None = None
+    limit: int | None = None
+    sort: str | None = None
+
+
+@dataclass
+class MediaCreateInput:
+    url: str
+    filename: str
+    mime_type: str
+    size: int
+    width: int | None = None
+    height: int | None = None
+    alt: str | None = None

pagekit_core-0.1.0/tests/test_client.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import pytest
+
+from pagekit import Pagekit, PagekitError
+from pagekit.http import DEFAULT_BASE_URL
+
+
+def test_throws_when_no_api_key():
+    with pytest.raises(PagekitError, match="api_key is required"):
+        Pagekit(api_key="")
+
+
+def test_creates_instance_with_valid_options():
+    client = Pagekit(api_key="pk_test_123")
+    assert client._http.api_key == "pk_test_123"
+    assert client._http.base_url == DEFAULT_BASE_URL
+    client.close()
+
+
+def test_uses_custom_base_url():
+    client = Pagekit(api_key="pk_test_123", base_url="https://my-api.example.com/v1/")
+    assert client._http.base_url == "https://my-api.example.com/v1"
+    client.close()
+
+
+def test_strips_trailing_slashes():
+    client = Pagekit(api_key="pk_test_123", base_url="https://example.com/v1///")
+    assert client._http.base_url == "https://example.com/v1"
+    client.close()
+
+
+def test_exposes_resource_namespaces():
+    client = Pagekit(api_key="pk_test_123")
+    assert client.posts is not None
+    assert client.authors is not None
+    assert client.categories is not None
+    assert client.tags is not None
+    assert client.media is not None
+    client.close()

pagekit_core-0.1.0/tests/test_errors.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from pagekit import PagekitError
+
+
+def test_has_correct_defaults():
+    error = PagekitError("test")
+    assert str(error) == "test"
+    assert error.status == 0
+    assert error.code == "api_error"
+
+
+def test_accepts_custom_status_and_code():
+    error = PagekitError("not found", status=404, code="not_found")
+    assert error.status == 404
+    assert error.code == "not_found"
+
+
+def test_stores_details():
+    details = {"field": "title"}
+    error = PagekitError("validation", status=422, code="validation_error", details=details)
+    assert error.details == details
+
+
+def test_is_auth_error_true_for_401():
+    assert PagekitError("unauthorized", status=401).is_auth_error is True
+
+
+def test_is_auth_error_true_for_403():
+    assert PagekitError("forbidden", status=403).is_auth_error is True
+
+
+def test_is_auth_error_false_for_other():
+    assert PagekitError("not found", status=404).is_auth_error is False
+    assert PagekitError("error", status=500).is_auth_error is False
+
+
+def test_is_rate_limited_true_for_429():
+    assert PagekitError("rate limited", status=429).is_rate_limited is True
+
+
+def test_is_rate_limited_false_for_other():
+    assert PagekitError("error", status=400).is_rate_limited is False
+
+
+def test_is_server_error_true_for_5xx():
+    assert PagekitError("error", status=500).is_server_error is True
+    assert PagekitError("error", status=503).is_server_error is True
+    assert PagekitError("error", status=599).is_server_error is True
+
+
+def test_is_server_error_false_for_non_5xx():
+    assert PagekitError("error", status=400).is_server_error is False
+    assert PagekitError("error", status=404).is_server_error is False

pagekit_core-0.1.0/tests/test_resources.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+from pagekit import Pagekit, PagekitError
+from pagekit.types import (
+    AuthorListParams,
+    MediaCreateInput,
+    PostCreateInput,
+    PostListParams,
+    PostStatus,
+    PostUpdateInput,
+)
+
+API_KEY = "pk_test_123"
+
+
+@respx.mock
+def test_posts_list():
+    respx.get("https://api.pagekit.app/v1/posts").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"page": 1, "limit": 10, "total": 0, "totalPages": 0, "hasNextPage": False, "hasPreviousPage": False}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    result = client.posts.list(PostListParams(status=PostStatus.PUBLISHED, limit=5))
+    assert result.data == []
+    assert result.pagination.page == 1
+    client.close()
+
+
+@respx.mock
+def test_posts_get():
+    respx.get("https://api.pagekit.app/v1/posts/123").mock(
+        return_value=httpx.Response(200, json={"id": "123", "title": "Test", "slug": "test", "content": "", "status": "published", "createdAt": "2024-01-01", "updatedAt": "2024-01-01", "tags": [], "seo": {}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    post = client.posts.get("123")
+    assert post.id == "123"
+    assert post.title == "Test"
+    client.close()
+
+
+@respx.mock
+def test_posts_get_by_slug():
+    respx.get("https://api.pagekit.app/v1/posts/slug/hello").mock(
+        return_value=httpx.Response(200, json={"id": "1", "title": "Hello", "slug": "hello", "content": "", "status": "published", "createdAt": "2024-01-01", "updatedAt": "2024-01-01", "tags": [], "seo": {}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    post = client.posts.get_by_slug("hello")
+    assert post.slug == "hello"
+    client.close()
+
+
+@respx.mock
+def test_posts_create():
+    respx.post("https://api.pagekit.app/v1/posts").mock(
+        return_value=httpx.Response(200, json={"id": "new", "title": "New Post", "slug": "new-post", "content": "Hello", "status": "draft", "createdAt": "2024-01-01", "updatedAt": "2024-01-01", "tags": [], "seo": {}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    post = client.posts.create(PostCreateInput(title="New Post", content="Hello"))
+    assert post.id == "new"
+    client.close()
+
+
+@respx.mock
+def test_posts_update():
+    respx.patch("https://api.pagekit.app/v1/posts/123").mock(
+        return_value=httpx.Response(200, json={"id": "123", "title": "Updated", "slug": "test", "content": "", "status": "draft", "createdAt": "2024-01-01", "updatedAt": "2024-01-01", "tags": [], "seo": {}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    post = client.posts.update("123", PostUpdateInput(title="Updated"))
+    assert post.title == "Updated"
+    client.close()
+
+
+@respx.mock
+def test_posts_delete():
+    respx.delete("https://api.pagekit.app/v1/posts/123").mock(
+        return_value=httpx.Response(204)
+    )
+    client = Pagekit(api_key=API_KEY)
+    client.posts.delete("123")
+    client.close()
+
+
+@respx.mock
+def test_authors_list():
+    respx.get("https://api.pagekit.app/v1/authors").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"page": 1, "limit": 10, "total": 0, "totalPages": 0, "hasNextPage": False, "hasPreviousPage": False}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    result = client.authors.list()
+    assert result.data == []
+    client.close()
+
+
+@respx.mock
+def test_authors_get():
+    respx.get("https://api.pagekit.app/v1/authors/a1").mock(
+        return_value=httpx.Response(200, json={"id": "a1", "name": "Alice"})
+    )
+    client = Pagekit(api_key=API_KEY)
+    author = client.authors.get("a1")
+    assert author.id == "a1"
+    client.close()
+
+
+@respx.mock
+def test_categories_list():
+    respx.get("https://api.pagekit.app/v1/categories").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"page": 1, "limit": 10, "total": 0, "totalPages": 0, "hasNextPage": False, "hasPreviousPage": False}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    result = client.categories.list()
+    assert result.data == []
+    client.close()
+
+
+@respx.mock
+def test_categories_get_by_slug():
+    respx.get("https://api.pagekit.app/v1/categories/engineering").mock(
+        return_value=httpx.Response(200, json={"id": "c1", "name": "Engineering", "slug": "engineering"})
+    )
+    client = Pagekit(api_key=API_KEY)
+    cat = client.categories.get_by_slug("engineering")
+    assert cat.slug == "engineering"
+    client.close()
+
+
+@respx.mock
+def test_tags_list():
+    respx.get("https://api.pagekit.app/v1/tags").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"page": 1, "limit": 10, "total": 0, "totalPages": 0, "hasNextPage": False, "hasPreviousPage": False}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    result = client.tags.list()
+    assert result.data == []
+    client.close()
+
+
+@respx.mock
+def test_media_list():
+    respx.get("https://api.pagekit.app/v1/media").mock(
+        return_value=httpx.Response(200, json={"data": [], "pagination": {"page": 1, "limit": 10, "total": 0, "totalPages": 0, "hasNextPage": False, "hasPreviousPage": False}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    result = client.media.list()
+    assert result.data == []
+    client.close()
+
+
+@respx.mock
+def test_media_create():
+    respx.post("https://api.pagekit.app/v1/media").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "url": "https://example.com/img.png", "filename": "img.png", "mimeType": "image/png", "size": 1024})
+    )
+    client = Pagekit(api_key=API_KEY)
+    media = client.media.create(MediaCreateInput(url="https://example.com/img.png", filename="img.png", mime_type="image/png", size=1024))
+    assert media.id == "m1"
+    client.close()
+
+
+@respx.mock
+def test_media_delete():
+    respx.delete("https://api.pagekit.app/v1/media/m1").mock(
+        return_value=httpx.Response(204)
+    )
+    client = Pagekit(api_key=API_KEY)
+    client.media.delete("m1")
+    client.close()
+
+
+@respx.mock
+def test_error_response():
+    respx.get("https://api.pagekit.app/v1/posts/999").mock(
+        return_value=httpx.Response(404, json={"error": {"message": "Not found", "code": "not_found"}})
+    )
+    client = Pagekit(api_key=API_KEY)
+    try:
+        client.posts.get("999")
+        assert False, "Should have raised"
+    except PagekitError as e:
+        assert e.status == 404
+        assert e.code == "not_found"
+    client.close()