python-kanka 2.5.0__tar.gz → 2.6.1__tar.gz

{python_kanka-2.5.0 → python_kanka-2.6.1}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.5.0
+current_version = 2.6.1
 commit = True
 tag = True
 tag_name = v{new_version}

python_kanka-2.6.1/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Prepare index page
+        run: mv docs/README.md docs/index.md
+
+      - name: Build MkDocs site
+        run: uv run mkdocs build --strict
+
+      - name: Restore README and copy raw markdown to site
+        run: |
+          mv docs/index.md docs/README.md
+          for f in docs/*.md; do
+            name="$(basename "$f")"
+            if [ "$name" != "README.md" ]; then
+              cp "$f" site/
+            fi
+          done
+          cp docs/README.md site/llms.txt
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{python_kanka-2.5.0 → python_kanka-2.6.1}/.github/workflows/publish.yml

@@ -56,7 +56,7 @@ jobs:
         uv build
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v6
       with:
         name: dist
         path: dist/
@@ -71,7 +71,7 @@ jobs:
 
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v6
+      uses: actions/download-artifact@v7
       with:
         name: dist
         path: dist/

{python_kanka-2.5.0 → python_kanka-2.6.1}/CLAUDE.md

@@ -142,6 +142,46 @@ Integration tests are NOT pytest tests - they have custom runners:
    - **Available in Kanka API but not yet implemented**: Timeline, Item, Relation, DiceRoll, Conversation, AttributeTemplate, Bookmark, Ability, Map, Inventory
    - **Never existed/removed**: EntityNote, EntityEvent, Attribute, Species
 
+## Version Bumping
+
+This project uses `bump2version` for version management. The version is tracked in three files:
+- `pyproject.toml` — package version
+- `src/kanka/_version.py` — runtime version
+- `.bumpversion.cfg` — bump2version's own tracking (must stay in sync)
+
+**To bump the version:**
+
+```bash
+# Patch (bug fixes): 2.4.1 → 2.4.2
+uv run bump2version patch
+
+# Minor (new features): 2.4.1 → 2.5.0
+uv run bump2version minor
+
+# Major (breaking changes): 2.4.1 → 3.0.0
+uv run bump2version major
+```
+
+This automatically:
+1. Updates the version in `pyproject.toml`, `src/kanka/_version.py`, and `.bumpversion.cfg`
+2. Creates a commit with message `Bump version: X.Y.Z → A.B.C`
+3. Creates a git tag `vA.B.C`
+
+**After bumping, always run `uv sync`** to update `uv.lock`, then amend the lock file into the bump commit and retag:
+
+```bash
+uv sync
+git add uv.lock
+git commit --amend --no-edit
+git tag -d vA.B.C
+git tag vA.B.C
+```
+
+**Important notes:**
+- The working tree must be clean before running bump2version (use `--allow-dirty` only if `.bumpversion.cfg` is the dirty file due to a sync fix)
+- If `.bumpversion.cfg`'s `current_version` is out of sync with the actual version in `pyproject.toml`, fix it manually before bumping
+- Use `feat` commits → minor bump, `fix` commits → patch bump
+
 ## Development Preferences
 
 - When executing test scripts with long output, redirect to file for parsing
@@ -204,6 +244,7 @@ When testing against the real API:
 - `docs/assets-and-images.md` — Assets, images, automatic image management
 - `docs/gallery.md` — Campaign gallery
 - `docs/search-and-filtering.md` — Search and filtering
+- `docs/last-sync.md` — Incremental sync using lastSync/sync
 - `docs/pagination.md` — Pagination
 - `docs/error-handling.md` — Exception types and patterns
 - `docs/rate-limiting.md` — Rate limit configuration

{python_kanka-2.5.0 → python_kanka-2.6.1}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install test lint format typecheck check clean coverage help sync build
+.PHONY: install test lint format typecheck check clean coverage help sync build docs-serve docs-build
 
 # Default target
 help:
@@ -13,6 +13,8 @@ help:
 	@echo "  make clean     - Clean up temporary files"
 	@echo "  make coverage  - Run tests with coverage report"
 	@echo "  make build     - Build the package"
+	@echo "  make docs-serve - Serve docs locally for preview"
+	@echo "  make docs-build - Build docs locally"
 
 # Install development dependencies and sync with lock file
 install:
@@ -71,3 +73,22 @@ coverage:
 # Build the package
 build:
 	uv build
+
+# Serve docs locally for preview
+docs-serve:
+	mv docs/README.md docs/index.md
+	uv run mkdocs serve || true
+	mv docs/index.md docs/README.md
+
+# Build docs locally
+docs-build:
+	mv docs/README.md docs/index.md
+	uv run mkdocs build --strict
+	mv docs/index.md docs/README.md
+	@for f in docs/*.md; do \
+		name=$$(basename "$$f"); \
+		if [ "$$name" != "README.md" ]; then \
+			cp "$$f" site/; \
+		fi; \
+	done
+	cp docs/README.md site/llms.txt

{python_kanka-2.5.0 → python_kanka-2.6.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: python-kanka
-Version: 2.5.0
+Version: 2.6.1
 Summary: Python client for the Kanka API
 Project-URL: Homepage, https://github.com/ervwalter/python-kanka
-Project-URL: Documentation, https://github.com/ervwalter/python-kanka#readme
+Project-URL: Documentation, https://python-kanka.ewal.dev/
 Project-URL: Repository, https://github.com/ervwalter/python-kanka
 Project-URL: Issues, https://github.com/ervwalter/python-kanka/issues
 Author-email: Erv Walter <erv@ewal.net>

python_kanka-2.6.1/docs/CNAME

@@ -0,0 +1 @@
+python-kanka.ewal.dev

{python_kanka-2.5.0 → python_kanka-2.6.1}/docs/README.md

@@ -12,6 +12,7 @@ A modern Python client for the [Kanka API](https://app.kanka.io/api-docs/1.0), t
 | [Entity Types Reference](entity-types-reference.md) | All 12 entity types with their specific fields |
 | [Posts](posts.md) | Attach notes and comments to any entity |
 | [Search and Filtering](search-and-filtering.md) | Global search, entities endpoint, list filters |
+| [Last Sync](last-sync.md) | Incremental sync using the lastSync/sync mechanism |
 | [Pagination](pagination.md) | Navigate large result sets |
 | [Assets and Images](assets-and-images.md) | File/link/alias assets, entity images, automatic image management |
 | [Campaign Gallery](gallery.md) | Campaign-level image storage |

{python_kanka-2.5.0 → python_kanka-2.6.1}/docs/api-reference.md

@@ -90,7 +90,12 @@ Get a single entity by its universal `entity_id`. Returns a raw dictionary.
 #### entities
 
 ```python
-entities(page: int = 1, limit: int = 15, **filters) → list[dict[str, Any]]
+entities(
+    page: int = 1,
+    limit: int = 15,
+    last_sync: str | None = None,
+    **filters,
+) → list[dict[str, Any]]
 ```
 
 Query the generic `/entities` endpoint. Returns raw dictionaries.
@@ -99,6 +104,7 @@ Query the generic `/entities` endpoint. Returns raw dictionaries.
 |-----------|------|---------|-------------|
 | `page` | `int` | `1` | Page number |
 | `limit` | `int` | `15` | Results per page |
+| `last_sync` | `str \| None` | `None` | Only return entities modified after this ISO 8601 timestamp. See [Last Sync](last-sync.md). |
 | `types` | `list[str]` | — | Filter by entity types |
 | `name` | `str` | — | Filter by name |
 | `tags` | `list[int]` | — | Filter by tag IDs |
@@ -149,8 +155,10 @@ Delete a gallery image by UUID.
 | `last_entities_meta` | `dict` | Pagination metadata from last `entities()` |
 | `last_entities_links` | `dict` | Pagination links from last `entities()` |
 | `entities_has_next_page` | `bool` | Whether next page exists for `entities()` |
+| `last_entities_sync` | `str \| None` | Sync timestamp from last `entities()` call. See [Last Sync](last-sync.md). |
 | `last_search_meta` | `dict` | Pagination metadata from last `search()` |
 | `last_search_links` | `dict` | Pagination links from last `search()` |
+| `last_search_sync` | `str \| None` | Sync timestamp from last `search()` call |
 | `last_gallery_meta` | `dict` | Pagination metadata from last `gallery()` |
 | `last_gallery_links` | `dict` | Pagination links from last `gallery()` |
 
@@ -203,6 +211,7 @@ list(
     page: int = 1,
     limit: int = 30,
     related: bool = False,
+    last_sync: str | None = None,
     **filters,
 ) → list[T]
 ```
@@ -214,6 +223,7 @@ List entities with optional filtering.
 | `page` | `int` | `1` | Page number |
 | `limit` | `int` | `30` | Results per page |
 | `related` | `bool` | `False` | Include posts and attributes |
+| `last_sync` | `str \| None` | `None` | Only return entities modified after this ISO 8601 timestamp. See [Last Sync](last-sync.md). |
 | `name` | `str` | — | Filter by name (partial match) |
 | `type` | `str` | — | Filter by entity type |
 | `types` | `list[str]` | — | Filter by multiple types |
@@ -223,7 +233,6 @@ List entities with optional filtering.
 | `updated_at` | `str` | — | Filter by update date |
 | `created_by` | `int` | — | Filter by creator ID |
 | `updated_by` | `int` | — | Filter by updater ID |
-| `lastSync` | `str` | — | Only entities modified after this ISO 8601 timestamp |
 
 **Returns:** List of entity model instances
 
@@ -438,6 +447,7 @@ delete_image(entity_or_id: T | int, is_header: bool = False) → bool
 | `pagination_meta` | `dict` | Metadata from last `list()` |
 | `pagination_links` | `dict` | Links from last `list()` |
 | `has_next_page` | `bool` | Whether next page exists |
+| `last_sync` | `str \| None` | Sync timestamp from last `list()` call. See [Last Sync](last-sync.md). |
 | `last_page_meta` | `dict` | Alias for `pagination_meta` |
 | `last_page_links` | `dict` | Alias for `pagination_links` |
 | `last_posts_meta` | `dict` | Metadata from last `list_posts()` |

{python_kanka-2.5.0 → python_kanka-2.6.1}/docs/entities.md

@@ -72,15 +72,17 @@ results = client.characters.list(
 )
 ```
 
-### The `lastSync` Filter
+### The `last_sync` Parameter
 
-Use the `lastSync` filter with an ISO 8601 timestamp to retrieve only entities modified after a specific time. This is useful for synchronization workflows:
+Use the `last_sync` parameter with an ISO 8601 timestamp to retrieve only entities modified after a specific time. This is useful for keeping a local cache in sync with Kanka without re-fetching everything. See [Last Sync](last-sync.md) for a complete guide including pagination, persistence, and important caveats.
 
 ```python
-from datetime import datetime, timedelta, timezone
+# Fetch all characters, capturing the sync timestamp
+characters = client.characters.list(page=1, limit=100)
+sync_timestamp = client.characters.last_sync
 
-last_sync = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
-updated = client.characters.list(lastSync=last_sync, related=True)
+# Later, fetch only characters that changed since then
+updated = client.characters.list(last_sync=sync_timestamp)
 ```
 
 ### Iterating All Pages

python_kanka-2.6.1/docs/last-sync.md

@@ -0,0 +1,132 @@
+# Last Sync
+
+The Kanka API provides a synchronization mechanism that lets you efficiently fetch only entities that have changed since your last request. This avoids repeatedly downloading your entire campaign and is essential for applications that need to keep a local cache or database in sync with Kanka.
+
+## How It Works
+
+Every list response from the Kanka API includes a top-level `sync` timestamp. This timestamp represents the exact moment the server processed your request. To get only entities that changed since then, pass that timestamp back as the `last_sync` parameter on your next request. The API returns only entities created or modified after that timestamp.
+
+The workflow is:
+
+1. **Initial fetch** — Call the API without `last_sync`. Capture the sync timestamp from the response.
+2. **Subsequent fetches** — Call the API with `last_sync` set to the previously captured value. Only modified entities are returned. Capture the new sync timestamp for next time.
+3. **Repeat** — Each call gives you a new sync timestamp to use on the next call.
+
+## Using last_sync with Entity Managers
+
+The `last_sync` parameter is a named parameter on all entity manager `list()` calls. After each call, the sync timestamp is available via the `last_sync` property.
+
+```python
+from kanka import KankaClient
+
+client = KankaClient(token="your-token", campaign_id=12345)
+
+# Initial fetch — get all characters
+characters = client.characters.list(page=1, limit=100)
+sync_timestamp = client.characters.last_sync
+print(f"Fetched {len(characters)} characters")
+print(f"Sync timestamp: {sync_timestamp}")
+
+# ... later, fetch only characters that changed ...
+updated = client.characters.list(last_sync=sync_timestamp)
+new_sync = client.characters.last_sync
+print(f"{len(updated)} characters changed since last sync")
+```
+
+## Using last_sync with the Generic Entities Endpoint
+
+The generic `client.entities()` endpoint also supports `last_sync` as a named parameter. This is useful when you want to sync all entity types at once rather than syncing each type separately. The sync timestamp is available via the `last_entities_sync` property.
+
+```python
+# Initial fetch — get all entities
+entities = client.entities(page=1, limit=100)
+sync_timestamp = client.last_entities_sync
+
+# ... later, fetch only entities that changed ...
+updated = client.entities(last_sync=sync_timestamp)
+new_sync = client.last_entities_sync
+print(f"{len(updated)} entities changed since last sync")
+```
+
+## Paginating with last_sync
+
+When your campaign has more entities than fit in a single page, you need to paginate through all pages on both the initial fetch and on subsequent syncs. Use the same `last_sync` value across all pages of a single sync operation, and capture the sync timestamp from the **first** page to use for the next sync.
+
+```python
+def sync_all_characters(client, last_sync=None):
+    """Fetch all characters, optionally only those changed since last_sync."""
+    all_characters = []
+    page = 1
+    next_sync = None
+
+    while True:
+        batch = client.characters.list(
+            page=page, limit=100, last_sync=last_sync
+        )
+        all_characters.extend(batch)
+
+        # Capture sync timestamp from the first page
+        if page == 1:
+            next_sync = client.characters.last_sync
+
+        if not client.characters.has_next_page:
+            break
+        page += 1
+
+    return all_characters, next_sync
+
+
+# Initial full sync
+characters, sync_timestamp = sync_all_characters(client)
+print(f"Full sync: {len(characters)} characters")
+
+# ... time passes, entities are modified in Kanka ...
+
+# Incremental sync — only fetches what changed
+changed, sync_timestamp = sync_all_characters(client, last_sync=sync_timestamp)
+print(f"Incremental sync: {len(changed)} characters changed")
+```
+
+## Persisting the Sync Timestamp
+
+For the sync pattern to work across application restarts, you need to persist the sync timestamp. How you store it depends on your application — a file, database, or configuration store all work:
+
+```python
+import json
+from pathlib import Path
+
+SYNC_FILE = Path("kanka_sync_state.json")
+
+
+def load_sync_state():
+    """Load the last sync timestamp from disk."""
+    if SYNC_FILE.exists():
+        return json.loads(SYNC_FILE.read_text())
+    return {}
+
+
+def save_sync_state(state):
+    """Save the sync timestamp to disk."""
+    SYNC_FILE.write_text(json.dumps(state, indent=2))
+
+
+# Load previous state
+state = load_sync_state()
+
+# Sync characters
+characters, new_sync = sync_all_characters(
+    client, last_sync=state.get("characters_sync")
+)
+state["characters_sync"] = new_sync
+
+# Save state for next run
+save_sync_state(state)
+```
+
+## Important Notes
+
+- **The sync timestamp is server-generated.** Always use the value from the API response rather than generating your own timestamp. This avoids clock skew issues between your machine and the Kanka server.
+- **`last_sync` filters by modification time.** It returns entities that were created or updated after the given timestamp. It does **not** tell you about deleted entities.
+- **Deleted entities are not included.** The `last_sync` response only contains entities that still exist. If you maintain a local cache, you may need a separate mechanism to detect deletions (e.g., periodically doing a full sync and comparing IDs).
+- **Use ISO 8601 format.** The sync value from the API is already in the correct format. If you construct a timestamp manually, use full ISO 8601 with timezone (e.g., `2026-02-25T01:35:39.768695Z`).
+- **Works with all filters.** You can combine `last_sync` with other filters like `type`, `name`, or `tags`. The API returns entities matching all filters that were also modified after the `last_sync` timestamp.

{python_kanka-2.5.0 → python_kanka-2.6.1}/docs/search-and-filtering.md

@@ -137,7 +137,7 @@ results = client.characters.list(
 | `updated_at` | `str` | Filter by update date (ISO format, supports `>=` prefix) |
 | `created_by` | `int` | Filter by creator user ID |
 | `updated_by` | `int` | Filter by last updater user ID |
-| `lastSync` | `str` | Only return entities modified after this ISO 8601 timestamp |
+| `last_sync` | `str` | Only return entities modified after this ISO 8601 timestamp |
 
 ### Filter Value Handling
 
@@ -147,14 +147,7 @@ results = client.characters.list(
 
 ### Sync Filter
 
-The `lastSync` filter is useful for synchronization workflows — it returns only entities that have been modified since the given timestamp:
-
-```python
-from datetime import datetime, timedelta, timezone
-
-last_sync = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
-updated_chars = client.characters.list(lastSync=last_sync, related=True)
-```
+The `last_sync` parameter returns only entities modified since a given timestamp. Each API response includes a sync timestamp (available via the `last_sync` property) that you should capture and reuse. See [Last Sync](last-sync.md) for a complete guide including the full sync workflow, pagination, persistence, and important caveats.
 
 ## Choosing the Right Approach
 

python_kanka-2.6.1/mkdocs.yml

@@ -0,0 +1,55 @@
+site_name: python-kanka
+site_url: https://python-kanka.ewal.dev/
+site_description: A modern Python client for the Kanka API
+repo_url: https://github.com/ervwalter/python-kanka
+repo_name: ervwalter/python-kanka
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.expand
+    - content.code.copy
+    - search.suggest
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Guides:
+      - Getting Started: getting-started.md
+      - Core Concepts: core-concepts.md
+      - Entity CRUD Operations: entities.md
+      - Entity Types Reference: entity-types-reference.md
+      - Posts: posts.md
+      - Search and Filtering: search-and-filtering.md
+      - Last Sync: last-sync.md
+      - Pagination: pagination.md
+      - Assets and Images: assets-and-images.md
+      - Campaign Gallery: gallery.md
+      - Error Handling: error-handling.md
+      - Rate Limiting: rate-limiting.md
+      - Debug Mode: debug-mode.md
+      - Known Limitations: known-limitations.md
+  - Reference:
+      - API Reference: api-reference.md
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - admonition
+  - tables
+  - toc:
+      permalink: true

{python_kanka-2.5.0 → python_kanka-2.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-kanka"
-version = "2.5.0"
+version = "2.6.1"
 description = "Python client for the Kanka API"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -33,11 +33,15 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/ervwalter/python-kanka"
-Documentation = "https://github.com/ervwalter/python-kanka#readme"
+Documentation = "https://python-kanka.ewal.dev/"
 Repository = "https://github.com/ervwalter/python-kanka"
 Issues = "https://github.com/ervwalter/python-kanka/issues"
 
 [dependency-groups]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
 dev = [
     "pytest==9.0.2",
     "pytest-asyncio==1.3.0",

{python_kanka-2.5.0 → python_kanka-2.6.1}/src/kanka/_version.py

@@ -1,3 +1,3 @@
 """Version information for python-kanka."""
 
-__version__ = "2.5.0"
+__version__ = "2.6.1"

{python_kanka-2.5.0 → python_kanka-2.6.1}/src/kanka/client.py

@@ -298,9 +298,10 @@ class KankaClient:
         params: dict[str, int | str] = {"page": page}
         response = self._request("GET", f"search/{term}", params=params)
 
-        # Store pagination metadata for access if needed
+        # Store pagination metadata and sync timestamp for access if needed
         self._last_search_meta = response.get("meta", {})
         self._last_search_links = response.get("links", {})
+        self._last_search_sync: str | None = response.get("sync")
 
         return [SearchResult(**item) for item in response["data"]]
 
@@ -322,7 +323,11 @@ class KankaClient:
         return response["data"]  # type: ignore[no-any-return]
 
     def entities(
-        self, page: int = 1, limit: int = 15, **filters
+        self,
+        page: int = 1,
+        limit: int = 15,
+        last_sync: str | None = None,
+        **filters,
     ) -> list[dict[str, Any]]:
         """Access the /entities endpoint with filters.
 
@@ -332,19 +337,28 @@ class KankaClient:
         Args:
             page: Page number (default: 1)
             limit: Number of results per page (default: 15)
+            last_sync: ISO 8601 timestamp; only return entities modified after
+                this time. Use the ``last_entities_sync`` property from a
+                previous call to implement incremental sync.
             **filters: Filter parameters like types, name, is_private, tags
 
         Returns:
             List of entity data
 
         Note:
-            Pagination information is available after calling entities():
+            After calling entities(), the following properties are available:
             - client.last_entities_meta: Contains total count, current page, etc.
             - client.last_entities_links: Contains URLs for first, last, prev, next
             - client.entities_has_next_page: True if more pages are available
+            - client.last_entities_sync: Server-generated sync timestamp for use
+              with the ``last_sync`` parameter on subsequent calls
         """
         params: dict[str, int | str] = {"page": page, "limit": limit}
 
+        # Add lastSync parameter for incremental sync
+        if last_sync is not None:
+            params["lastSync"] = last_sync
+
         # Handle special filters
         if "types" in filters and isinstance(filters["types"], list):
             params["types"] = ",".join(filters["types"])
@@ -367,6 +381,7 @@ class KankaClient:
         response = self._request("GET", "entities", params=params)
         self._last_entities_meta = response.get("meta", {})
         self._last_entities_links = response.get("links", {})
+        self._last_entities_sync: str | None = response.get("sync")
         return response["data"]  # type: ignore[no-any-return]
 
     def _parse_rate_limit_headers(self, response) -> float | None:
@@ -705,6 +720,15 @@ class KankaClient:
         """
         return getattr(self, "_last_search_links", {})
 
+    @property
+    def last_search_sync(self) -> str | None:
+        """Get the sync timestamp from the last search() call.
+
+        Returns:
+            The sync timestamp string, or None if search() has not been called.
+        """
+        return getattr(self, "_last_search_sync", None)
+
     @property
     def last_entities_meta(self) -> dict[str, Any]:
         """Get metadata from the last entities() call.
@@ -724,6 +748,19 @@ class KankaClient:
         """
         return getattr(self, "_last_entities_links", {})
 
+    @property
+    def last_entities_sync(self) -> str | None:
+        """Get the sync timestamp from the last entities() call.
+
+        This is a server-generated ISO 8601 timestamp representing when the
+        response was produced. Pass it as the ``last_sync`` parameter on a
+        subsequent ``entities()`` call to fetch only entities modified since then.
+
+        Returns:
+            The sync timestamp string, or None if entities() has not been called.
+        """
+        return getattr(self, "_last_entities_sync", None)
+
     @property
     def entities_has_next_page(self) -> bool:
         """Check if more pages are available from the last entities() call."""