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

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

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

{python_kanka-2.5.0 → python_kanka-2.6.0}/.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.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kanka
-Version: 2.5.0
+Version: 2.6.0
 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

{python_kanka-2.5.0 → python_kanka-2.6.0}/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.0}/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.0}/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.0/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.0}/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.5.0 → python_kanka-2.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-kanka"
-version = "2.5.0"
+version = "2.6.0"
 description = "Python client for the Kanka API"
 readme = "README.md"
 requires-python = ">=3.12"

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

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

{python_kanka-2.5.0 → python_kanka-2.6.0}/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."""

{python_kanka-2.5.0 → python_kanka-2.6.0}/src/kanka/managers.py

@@ -80,7 +80,12 @@ class EntityManager[T: Entity]:
         return bool(self.pagination_links.get("next"))
 
     def list(
-        self, page: int = 1, limit: int = 30, related: bool = False, **filters
+        self,
+        page: int = 1,
+        limit: int = 30,
+        related: bool = False,
+        last_sync: str | None = None,
+        **filters,
     ) -> list[T]:
         """List entities with optional filters.
 
@@ -88,6 +93,9 @@ class EntityManager[T: Entity]:
             page: Page number (default: 1)
             limit: Number of results per page (default: 30)
             related: Include related data (posts, attributes, etc.)
+            last_sync: ISO 8601 timestamp; only return entities modified after
+                this time. Use the ``last_sync`` property from a previous call
+                to implement incremental sync.
             **filters: Additional filters supported by the API
 
         Supported filters:
@@ -104,10 +112,12 @@ class EntityManager[T: Entity]:
             List of entity instances
 
         Note:
-            Pagination information is available after calling list():
+            After calling list(), the following properties are available:
             - manager.pagination_meta: Contains total count, current page, etc.
             - manager.pagination_links: Contains URLs for first, last, prev, next
             - manager.has_next_page: True if more pages are available
+            - manager.last_sync: Server-generated sync timestamp for use with
+              the ``last_sync`` parameter on subsequent calls
 
         Examples:
             # Get all public characters
@@ -154,6 +164,10 @@ class EntityManager[T: Entity]:
         if related:
             params["related"] = 1
 
+        # Add lastSync parameter for incremental sync
+        if last_sync is not None:
+            params["lastSync"] = last_sync
+
         # Add filters
         for key, value in filters.items():
             if value is not None:
@@ -175,9 +189,10 @@ class EntityManager[T: Entity]:
 
         response = self.client._request("GET", self.endpoint, params=params)
 
-        # Store pagination metadata on the manager for access if needed
+        # Store pagination metadata and sync timestamp for access if needed
         self._last_meta = response.get("meta", {})
         self._last_links = response.get("links", {})
+        self._last_sync: str | None = response.get("sync")
 
         return [self.model(**item) for item in response["data"]]
 
@@ -379,6 +394,19 @@ class EntityManager[T: Entity]:
         """
         return getattr(self, "_last_links", {})
 
+    @property
+    def last_sync(self) -> str | None:
+        """Get the sync timestamp from the last list() 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 ``list()`` call to fetch only entities modified since then.
+
+        Returns:
+            The sync timestamp string, or None if list() has not been called.
+        """
+        return getattr(self, "_last_sync", None)
+
     def _extract_entity_id(self, entity_or_id: T | int) -> int:
         """Extract entity_id from an entity object or integer.
 

{python_kanka-2.5.0 → python_kanka-2.6.0}/tests/integration/test_entities_api_integration.py

@@ -398,6 +398,140 @@ class TestEntitiesApiIntegration(IntegrationTestBase):
 
         print("  Verified entity structure for generic API response")
 
+    def test_sync_timestamp(self):
+        """Test that entities() captures sync and last_sync filters correctly."""
+        # Verify last_entities_sync is None before any call
+        self.assert_true(
+            self.client.last_entities_sync is None,
+            "last_entities_sync should be None before any entities() call",
+        )
+
+        # Initial call — capture the sync timestamp
+        self.client.entities(limit=1)
+        sync_ts = self.client.last_entities_sync
+
+        self.assert_not_none(
+            sync_ts, "last_entities_sync should not be None after call"
+        )
+        self.assert_true(
+            isinstance(sync_ts, str) and len(sync_ts) > 0,
+            "last_entities_sync should be a non-empty string",
+        )
+        print(f"  Initial sync timestamp: {sync_ts}")
+
+        # Nothing should have changed yet
+        self.wait_for_api()
+        unchanged = self.client.entities(last_sync=sync_ts)
+        print(f"  Before creating entity: {len(unchanged)} entities changed")
+
+        # Now create an entity — this should show up as changed
+        self.wait_for_api()
+        character = self.client.characters.create(
+            name=f"Sync Test Character - DELETE ME - {datetime.now().isoformat()}",
+            type="NPC",
+        )
+        self._register_entity_cleanup("characters", character.id, character.name)
+
+        self.wait_for_api()
+
+        # Fetch with the old sync timestamp — the new entity should appear
+        updated = self.client.entities(last_sync=sync_ts)
+        new_sync = self.client.last_entities_sync
+
+        self.assert_true(
+            len(updated) > 0,
+            "Should find at least 1 entity changed after creating one",
+        )
+        self.assert_not_none(
+            new_sync, "last_entities_sync should be set after lastSync call"
+        )
+
+        # Verify the created entity is in the results
+        found = any(e.get("child_id") == character.id for e in updated)
+        self.assert_true(
+            found,
+            f"Created character (ID {character.id}) should appear in lastSync results",
+        )
+
+        # Fetch again with the NEW sync timestamp — should get nothing new
+        self.wait_for_api()
+        updated_again = self.client.entities(last_sync=new_sync)
+        self.assert_equal(
+            len(updated_again),
+            0,
+            f"No entities should have changed since new sync, got {len(updated_again)}",
+        )
+
+        print(f"  After creating entity: {len(updated)} entities changed")
+        print(
+            f"  After second sync: {len(updated_again)} entities changed (expected 0)"
+        )
+
+    def test_entity_manager_sync_timestamp(self):
+        """Test that EntityManager.list() captures sync and last_sync filters correctly."""
+        # Verify last_sync is None before any call
+        self.assert_true(
+            self.client.characters.last_sync is None,
+            "last_sync should be None before any list() call",
+        )
+
+        # Initial call — capture the sync timestamp
+        self.client.characters.list(limit=1)
+        sync_ts = self.client.characters.last_sync
+
+        self.assert_not_none(sync_ts, "last_sync should not be None after list()")
+        self.assert_true(
+            isinstance(sync_ts, str) and len(sync_ts) > 0,
+            "last_sync should be a non-empty string",
+        )
+        print(f"  Characters sync timestamp: {sync_ts}")
+
+        # Nothing should have changed yet
+        self.wait_for_api()
+        unchanged = self.client.characters.list(last_sync=sync_ts)
+        print(f"  Before creating character: {len(unchanged)} characters changed")
+
+        # Create a character — this should show up
+        self.wait_for_api()
+        character = self.client.characters.create(
+            name=f"Sync Test Character - DELETE ME - {datetime.now().isoformat()}",
+            type="NPC",
+        )
+        self._register_entity_cleanup("characters", character.id, character.name)
+
+        self.wait_for_api()
+
+        # Fetch with old sync timestamp — the new character should appear
+        updated = self.client.characters.list(last_sync=sync_ts)
+        new_sync = self.client.characters.last_sync
+
+        self.assert_true(
+            len(updated) > 0,
+            "Should find at least 1 character changed after creating one",
+        )
+        self.assert_not_none(new_sync, "last_sync should be set after lastSync call")
+
+        # Verify the created character is in the results
+        found = any(c.id == character.id for c in updated)
+        self.assert_true(
+            found,
+            f"Created character (ID {character.id}) should appear in lastSync results",
+        )
+
+        # Fetch again with the NEW sync — should get nothing new
+        self.wait_for_api()
+        updated_again = self.client.characters.list(last_sync=new_sync)
+        self.assert_equal(
+            len(updated_again),
+            0,
+            f"No characters should have changed since new sync, got {len(updated_again)}",
+        )
+
+        print(f"  After creating character: {len(updated)} characters changed")
+        print(
+            f"  After second sync: {len(updated_again)} characters changed (expected 0)"
+        )
+
     def run_all_tests(self):
         """Run all entities API integration tests."""
         tests = [
@@ -409,6 +543,8 @@ class TestEntitiesApiIntegration(IntegrationTestBase):
             ("Filter by Tags", self.test_filter_with_tags),
             ("Combined Filters", self.test_combined_filters),
             ("Entity Response Structure", self.test_entity_response_structure),
+            ("Sync Timestamp", self.test_sync_timestamp),
+            ("Entity Manager Sync Timestamp", self.test_entity_manager_sync_timestamp),
         ]
 
         results = []

{python_kanka-2.5.0 → python_kanka-2.6.0}/tests/test_client.py

@@ -265,6 +265,96 @@ class TestKankaClient:
         assert client.last_entities_links == {}
         assert client.entities_has_next_page is False
 
+    @patch("requests.Session")
+    def test_entities_sync_captured(self, mock_session_class):
+        """Test that entities() captures the sync timestamp."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        sync_ts = "2025-06-15T10:30:00.123456Z"
+        mock_response = MockResponse(
+            create_api_response(
+                [{"id": 1, "name": "Test", "type": "character"}], sync=sync_ts
+            ),
+            status_code=200,
+        )
+        mock_session.request.return_value = mock_response
+
+        client = KankaClient(token="test_token", campaign_id=123)
+        client.entities()
+
+        assert client.last_entities_sync == sync_ts
+
+    @patch("requests.Session")
+    def test_entities_sync_default_is_none(self, mock_session_class):
+        """Test that last_entities_sync is None before any call."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        client = KankaClient(token="test_token", campaign_id=123)
+
+        assert client.last_entities_sync is None
+
+    @patch("requests.Session")
+    def test_entities_last_sync_parameter(self, mock_session_class):
+        """Test that last_sync parameter sends lastSync query param."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        mock_response = MockResponse(
+            create_api_response([], sync="2025-06-15T11:00:00.000000Z"),
+            status_code=200,
+        )
+        mock_session.request.return_value = mock_response
+
+        client = KankaClient(token="test_token", campaign_id=123)
+        sync_ts = "2025-06-15T10:00:00.000000Z"
+        client.entities(last_sync=sync_ts)
+
+        # Verify lastSync was included in the request params
+        call_args = mock_session.request.call_args
+        assert "lastSync" in call_args[1]["params"]
+        assert call_args[1]["params"]["lastSync"] == sync_ts
+
+    @patch("requests.Session")
+    def test_search_sync_captured(self, mock_session_class):
+        """Test that search() captures the sync timestamp."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        sync_ts = "2025-06-15T10:30:00.123456Z"
+        search_data = [
+            {
+                "id": 1,
+                "entity_id": 100,
+                "name": "Dragon",
+                "type": "character",
+                "url": "https://app.kanka.io/w/1/entities/100",
+                "is_private": False,
+                "tags": [],
+            }
+        ]
+        mock_response = MockResponse(
+            create_api_response(search_data, sync=sync_ts),
+            status_code=200,
+        )
+        mock_session.request.return_value = mock_response
+
+        client = KankaClient(token="test_token", campaign_id=123)
+        client.search("dragon")
+
+        assert client.last_search_sync == sync_ts
+
+    @patch("requests.Session")
+    def test_search_sync_default_is_none(self, mock_session_class):
+        """Test that last_search_sync is None before any call."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        client = KankaClient(token="test_token", campaign_id=123)
+
+        assert client.last_search_sync is None
+
     @patch("requests.Session")
     def test_request_error_handling(self, mock_session_class):
         """Test error handling in _request method."""

{python_kanka-2.5.0 → python_kanka-2.6.0}/tests/test_managers.py

@@ -145,6 +145,60 @@ class TestEntityManager:
         call_args = self.mock_client._request.call_args
         assert call_args[1]["params"]["types"] == "character,npc"
 
+    def test_list_captures_sync_timestamp(self):
+        """Test that list() captures the sync timestamp from the response."""
+        mock_data = [create_mock_entity("character", 1)]
+        sync_ts = "2025-06-15T10:30:00.123456Z"
+        mock_response = create_api_response(mock_data, sync=sync_ts)
+        self.mock_client._request.return_value = mock_response
+
+        self.manager.list()
+
+        assert self.manager.last_sync == sync_ts
+
+    def test_last_sync_is_none_before_list(self):
+        """Test that last_sync is None before any list() call."""
+        assert self.manager.last_sync is None
+
+    def test_last_sync_updates_on_subsequent_calls(self):
+        """Test that last_sync updates with each list() call."""
+        first_sync = "2025-06-15T10:00:00.000000Z"
+        second_sync = "2025-06-15T11:00:00.000000Z"
+
+        self.mock_client._request.return_value = create_api_response(
+            [], sync=first_sync
+        )
+        self.manager.list()
+        assert self.manager.last_sync == first_sync
+
+        self.mock_client._request.return_value = create_api_response(
+            [], sync=second_sync
+        )
+        self.manager.list()
+        assert self.manager.last_sync == second_sync
+
+    def test_list_with_last_sync_parameter(self):
+        """Test that last_sync parameter is sent as lastSync query param."""
+        self.mock_client._request.return_value = create_api_response([])
+        sync_ts = "2025-06-15T10:00:00.000000Z"
+
+        self.manager.list(last_sync=sync_ts)
+
+        self.mock_client._request.assert_called_with(
+            "GET",
+            "characters",
+            params={"page": 1, "limit": 30, "lastSync": sync_ts},
+        )
+
+    def test_list_without_last_sync_omits_param(self):
+        """Test that lastSync is not sent when last_sync is None."""
+        self.mock_client._request.return_value = create_api_response([])
+
+        self.manager.list()
+
+        call_params = self.mock_client._request.call_args[1]["params"]
+        assert "lastSync" not in call_params
+
     def test_create_entity(self):
         """Test creating an entity."""
         # Setup mock response

{python_kanka-2.5.0 → python_kanka-2.6.0}/tests/utils.py

@@ -154,7 +154,10 @@ def create_mock_search_result(
 
 
 def create_api_response(
-    data: Any, meta: dict | None = None, links: dict | None = None
+    data: Any,
+    meta: dict | None = None,
+    links: dict | None = None,
+    sync: str | None = "2025-01-15T12:00:00.000000Z",
 ) -> dict[str, Any]:
     """Create a mock API response with standard structure.
 
@@ -162,6 +165,8 @@ def create_api_response(
         data: The response data (single item or list)
         meta: Pagination metadata
         links: Pagination links
+        sync: Sync timestamp (included by default for list responses,
+            matching real API behavior). Pass None to omit.
 
     Returns:
         Dict representing an API response
@@ -196,6 +201,10 @@ def create_api_response(
                 "next": None,
             }
 
+    # Include sync timestamp for list responses, matching real API behavior
+    if sync is not None and isinstance(data, list):
+        response["sync"] = sync
+
     return response
 
 

{python_kanka-2.5.0 → python_kanka-2.6.0}/uv.lock

@@ -853,7 +853,7 @@ wheels = [
 
 [[package]]
 name = "python-kanka"
-version = "2.5.0"
+version = "2.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },