zop-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{zop_cli-0.2.0 → zop_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zop-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: High-throughput Zotero CLI focused on batch operations and automation
 Project-URL: Homepage, https://github.com/anomalyco/zop
 Project-URL: Issues, https://github.com/anomalyco/zop/issues
@@ -50,7 +50,7 @@ uv sync
 
 ## 配置
 
-新建 `~/.config/zop/config.toml`:
+zop 按以下顺序查找配置(首个存在的文件生效):`ZOP_CONFIG` 环境变量 → 平台配置目录(platformdirs)→ `~/.config/zop/config.toml`。平台配置目录:Windows 为 `%LOCALAPPDATA%\zop\`、macOS 为 `~/Library/Application Support/zop/`、Linux 为 `~/.config/zop/`。在任一位置创建 `config.toml`:
 
 ```toml
 [zotero]

{zop_cli-0.2.0 → zop_cli-0.2.1}/README.md

@@ -22,7 +22,7 @@ uv sync
 
 ## 配置
 
-新建 `~/.config/zop/config.toml`:
+zop 按以下顺序查找配置(首个存在的文件生效):`ZOP_CONFIG` 环境变量 → 平台配置目录(platformdirs)→ `~/.config/zop/config.toml`。平台配置目录:Windows 为 `%LOCALAPPDATA%\zop\`、macOS 为 `~/Library/Application Support/zop/`、Linux 为 `~/.config/zop/`。在任一位置创建 `config.toml`:
 
 ```toml
 [zotero]

{zop_cli-0.2.0 → zop_cli-0.2.1}/skills/zop/SKILL.md

@@ -15,7 +15,7 @@ Install, then point it at a library:
 uv tool install zop-cli          # the command is `zop`
 ```
 
-Config at `~/.config/zop/config.toml` (or `$ZOP_CONFIG`):
+Config search order: `$ZOP_CONFIG` → platform dir (Windows `%LOCALAPPDATA%\zop\`, macOS `~/Library/Application Support/zop/`, Linux `~/.config/zop/`) → `~/.config/zop/config.toml`. Put it at any of these:
 
 ```toml
 [zotero]
@@ -43,6 +43,8 @@ Every command prints exactly one JSON object to stdout:
 
 Always `json.loads(stdout)` and branch on `ok`. Never string-match the output.
 
+**`export` is special**: in non-tty/JSON mode it returns `{ok, data: {format, content, count}}` where `content` is the raw bibtex/ris string or the csl-json array. In tty mode (or with `--out FILE`) it writes the raw format directly (pipe-friendly: `zop export K > refs.bib`).
+
 ## Commands
 
 ### Reads (offline, no key needed)
@@ -67,9 +69,9 @@ Always `json.loads(stdout)` and branch on `ok`. Never string-match the output.
 
 | Goal | Command |
 |------|---------|
-| Create collection (+ parent by name) | `zop collection create "Name" [--parent "ParentName"]` |
+| Create collection (+ parent) | `zop collection create "Name" [--parent "ParentKeyOrName"]` |
 | Delete collection (cascades) | `zop collection delete <KEY> [-y]` |
-| Move collection under new parent | `zop collection reparent <KEY> [--parent "Name"]` |
+| Move collection under new parent | `zop collection reparent <KEY> [--parent "KeyOrName"]` |
 | Move items into a collection | `zop collection move <K1> <K2> --to <KEY>` |
 | Update item metadata | `zop item update <KEY> [--title ...] [--set K=V]` |
 | Add items by DOI | `zop item add --doi 10.x/y [--doi ...] [--from-file dois.txt]` |
@@ -78,7 +80,7 @@ Always `json.loads(stdout)` and branch on `ok`. Never string-match the output.
 | Remove tags | `zop tag remove <KEY...> --tags t1,t2` |
 | Add a note | `zop note add <KEY> --text "..." [--file note.md]` |
 
-Name→key resolution is automatic in write commands (`--parent "Name"`), so accept either from the user.
+Parent references accept a KEY or a NAME in write commands (`--parent "KeyOrName"`); a NAME is resolved locally first, then via the Web API if not yet synced. Accept either from the user.
 
 ### Batch reorg (zop's highlight)
 
@@ -86,7 +88,7 @@ Author a plan JSON, **dry-run to validate**, then execute:
 
 ```bash
 zop collection plan plan.json --dry-run      # checks name conflicts, parent resolution, item existence
-zop collection plan plan.json --execute      # topologically creates collections in waves
+zop collection plan plan.json --execute      # creates collections (topo order), then moves items into them
 ```
 
 Plan shape:
@@ -97,6 +99,8 @@ Plan shape:
 
 Always inspect the dry-run `unresolved_parents` / `conflicts` before `--execute`. Intra-plan parents (a new collection whose parent is another new collection) are supported and created in topological order.
 
+On `--execute`, the envelope reports `assignments_done` (`[item_key, coll_key]` pairs actually moved) and `assignments_failed` (`[item_key, error]`). Items move via the API, so they land in the new collections even before Zotero syncs them locally.
+
 For every flag of any command, run `zop <command> --help` rather than guessing.
 
 ## Working as an agent
@@ -105,3 +109,5 @@ For every flag of any command, run `zop <command> --help` rather than guessing.
 - **For multi-step reorgs, author a plan and `--dry-run`** — let zop validate conflicts; don't reimplement the checks.
 - **Batch writes isolate failures**: `collection move`, `tag add/remove`, and `item delete` return per-item success/failure in one envelope and don't abort the batch. Report which keys failed from the `failed` array; exit code `2` means partial failure.
 - **Versions matter for writes**: if a write fails with `conflict`, the item changed server-side — re-read and retry rather than looping blindly.
+- **Reads lag writes briefly**: writes hit the Web API, reads use the local SQLite snapshot. A just-created collection/item isn't visible to read commands until Zotero syncs it (seconds to minutes). To chain creates, pass the returned KEY (e.g. `--parent <KEY>`) rather than the new NAME — or rely on the NAME→API fallback.
+- **stats vs recent count differently**: `stats` is a full overview — it counts annotations/highlights in `total_items` and `by_type`. `recent`/`search`/`duplicates` list only bibliographic items (annotations have no title, so they'd be empty noise in a list). Don't expect the two counts to match.

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/_version.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/adapters/sqlite_reader.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from zop.core.errors import NotFoundError, ValidationError
 from zop.models.collection import Collection, CollectionTree
 from zop.models.common import ItemType
-from zop.models.item import Item, ItemSummary
+from zop.models.item import Item, ItemSummary, parse_year
 
 
 class SqliteReader:
@@ -51,8 +51,9 @@ class SqliteReader:
                        c.version, c.synced, p.key AS parent_key,
                        (SELECT COUNT(*) FROM collectionItems ci
                           JOIN items i ON i.itemID = ci.itemID
+                          JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
                           WHERE ci.collectionID = c.collectionID
-                            AND i.itemTypeID NOT IN (1, 14)) AS item_count
+                            AND it.typeName NOT IN ('attachment', 'note', 'annotation')) AS item_count
                 FROM collections c
                 LEFT JOIN collections p ON p.collectionID = c.parentCollectionID
                 WHERE c.libraryID = ?
@@ -200,6 +201,7 @@ class SqliteReader:
             tags=tags,
             collections=colls,
             version=version,
+            year=parse_year(date),
             date=date,
             date_added=str(date_added) if date_added else None,
             date_modified=str(date_modified) if date_modified else None,
@@ -259,7 +261,7 @@ class SqliteReader:
                 FROM items i
                 JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
                 WHERE i.libraryID = ?
-                  AND i.itemTypeID NOT IN (1, 14)  -- exclude attachments & notes
+                  AND it.typeName NOT IN ('attachment', 'note', 'annotation')
                   AND (
                     EXISTS (SELECT 1 FROM itemData id JOIN fields f ON f.fieldID=id.fieldID
                               JOIN itemDataValues iv ON iv.valueID=id.valueID
@@ -281,6 +283,7 @@ class SqliteReader:
                 item_type=ItemType(r[1]) if r[1] else ItemType.UNKNOWN,
                 title=r[4] or "",
                 creators=[c.strip() for c in (r[3] or "").split(";") if c.strip()],
+                year=parse_year(r[5]),
                 date=r[5],
             )
             for r in rows
@@ -304,7 +307,7 @@ class SqliteReader:
                 FROM items i
                 JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
                 WHERE i.libraryID = ?
-                  AND i.itemTypeID NOT IN (1, 14)
+                  AND it.typeName NOT IN ('attachment', 'note', 'annotation')
                   AND i.dateAdded >= datetime('now', ?)
                 ORDER BY i.dateAdded DESC
                 LIMIT ?
@@ -317,6 +320,7 @@ class SqliteReader:
                 item_type=ItemType(r[1]) if r[1] else ItemType.UNKNOWN,
                 title=r[4] or "",
                 creators=[c.strip() for c in (r[3] or "").split(";") if c.strip()],
+                year=parse_year(r[5]),
                 date=r[5],
             )
             for r in rows
@@ -362,14 +366,16 @@ class SqliteReader:
         """Return counts: total items, by type, top tags, collection count, etc."""
         with self._connect() as con:
             total = con.execute(
-                "SELECT COUNT(*) FROM items WHERE libraryID=? AND itemTypeID NOT IN (1,14)",
+                "SELECT COUNT(*) FROM items WHERE libraryID=? "
+                "AND itemTypeID NOT IN (SELECT itemTypeID FROM itemTypes "
+                "WHERE typeName IN ('attachment', 'note'))",
                 (library_id,),
             ).fetchone()[0]
             by_type_rows = con.execute(
                 """
                 SELECT it.typeName, COUNT(*) FROM items i
                 JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
-                WHERE i.libraryID=? AND i.itemTypeID NOT IN (1,14)
+                WHERE i.libraryID=? AND it.typeName NOT IN ('attachment', 'note')
                 GROUP BY it.typeName ORDER BY 2 DESC
                 """,
                 (library_id,),
@@ -448,7 +454,9 @@ class SqliteReader:
                     JOIN fields f ON f.fieldID = id.fieldID
                     JOIN itemDataValues iv ON iv.valueID = id.valueID
                     JOIN items i ON i.itemID = id.itemID
+                    JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
                     WHERE f.fieldName = 'DOI' AND i.libraryID = ?
+                      AND it.typeName NOT IN ('attachment', 'note', 'annotation')
                       AND iv.value IS NOT NULL AND iv.value != ''
                     GROUP BY iv.value
                     HAVING COUNT(*) > 1
@@ -465,7 +473,9 @@ class SqliteReader:
                     JOIN fields f ON f.fieldID = id.fieldID
                     JOIN itemDataValues iv ON iv.valueID = id.valueID
                     JOIN items i ON i.itemID = id.itemID
+                    JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
                     WHERE f.fieldName = 'title' AND i.libraryID = ?
+                      AND it.typeName NOT IN ('attachment', 'note', 'annotation')
                       AND iv.value IS NOT NULL AND iv.value != ''
                     GROUP BY iv.value
                     HAVING COUNT(*) > 1

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/adapters/zotero_api.py

@@ -120,6 +120,15 @@ class ZoteroApi:
             start += len(data)
         return out
 
+    async def get_collection(self, key: str) -> dict[str, Any]:
+        """Fetch a single collection by key (GET /collections/{key}).
+
+        Used to read the current ``version`` for the If-Unmodified-Since-
+        Version header before a PATCH/DELETE.
+        """
+        resp = await self._client.get(self._coll_url(key))
+        return cast("dict[str, Any]", self._check(resp))
+
     async def create_collections(
         self, payloads: Sequence[dict[str, Any]]
     ) -> list[dict[str, Any]]:

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/commands/collection.py

@@ -13,6 +13,7 @@ from zop.adapters.zotero_api import ApiCreds
 from zop.core.config import load_config
 from zop.core.envelope import emit, emit_batch, emit_error
 from zop.core.errors import ZopError
+from zop.models.collection import Collection
 from zop.services.collections import CollectionsService, PlanNode
 
 
@@ -73,13 +74,13 @@ def items_cmd(ctx: click.Context, key: str) -> None:
 
 @collection.command("create")
 @click.argument("name")
-@click.option("--parent", "parent_name", default=None, help="Parent collection NAME.")
+@click.option("--parent", "parent_ref", default=None, help="Parent collection KEY or NAME.")
 @click.pass_context
-def create_cmd(ctx: click.Context, name: str, parent_name: str | None) -> None:
-    """Create a collection (NAME). Requires API key."""
+def create_cmd(ctx: click.Context, name: str, parent_ref: str | None) -> None:
+    """Create a collection (NAME). Parent may be a KEY or NAME. Requires API key."""
     try:
         svc = _service(ctx)
-        result = asyncio.run(svc.create(name, parent=parent_name))
+        result = asyncio.run(svc.create(name, parent=parent_ref))
         emit([result.model_dump()], human=_human(), count=1)
     except ZopError as e:
         emit_error(e, human=_human())
@@ -199,17 +200,24 @@ def plan_cmd(
         if not report.ok:
             emit(out, human=_human())
             sys.exit(2)
-        created = asyncio.run(svc.create_many(plan))
+        async def _execute() -> tuple[list[Collection], list[tuple[str, str]], list[tuple[str, str]]]:
+            created = await svc.create_many(plan)
+            created_by_name = {c.name: c.key for c in created}
+            done, failed = await svc.execute_assignments(
+                report.item_assignments, created_by_name
+            )
+            return created, done, failed
+
+        created, done, failed = asyncio.run(_execute())
         emit(
             {
                 "created": [c.model_dump() for c in created],
-                "assignments_pending": report.item_assignments,
+                "assignments_done": done,
+                "assignments_failed": failed,
             },
             human=_human(),
             count=len(created),
         )
-        # Note: item assignment to newly-created collections would go here
-        # in a follow-up step (separate API call after collections exist).
     except ZopError as e:
         emit_error(e, human=_human())
         sys.exit(1)

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/commands/export.py

@@ -59,13 +59,21 @@ def export_cmd(
                 Path(out).write_text(str(payload), encoding="utf-8")
             emit({"written": out, "count": len(items)}, human=_human())
         else:
-            if fmt == "csl-json":
-                import json
-                sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False))
-                sys.stdout.write("\n")
+            if _human():
+                # Human/tty: raw output (pipe-friendly, e.g. zop export K > refs.bib).
+                if fmt == "csl-json":
+                    import json
+                    sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False))
+                    sys.stdout.write("\n")
+                else:
+                    sys.stdout.write(str(payload))
+                sys.stdout.flush()
             else:
-                sys.stdout.write(str(payload))
-            sys.stdout.flush()
+                # JSON/agent: wrap in the standard envelope.
+                emit(
+                    {"format": fmt, "content": payload, "count": len(items)},
+                    human=False,
+                )
     except ZopError as e:
         emit_error(e, human=_human())
         sys.exit(1)

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/core/config.py

@@ -1,8 +1,10 @@
 """Configuration loader.
 
-Reads ``~/.config/zop/config.toml`` (or an explicit path from the
-``ZOP_CONFIG`` env var). Supports a flat TOML schema only in v0.1 — a
-profile-based schema is on the roadmap.
+Reads config from the first existing of: an explicit path, the
+``ZOP_CONFIG`` env var, the platform-specific user config dir
+(``platformdirs``), or ``~/.config/zop/config.toml`` as a fallback.
+Supports a flat TOML schema only in v0.1 — a profile-based schema is on
+the roadmap.
 """
 
 from __future__ import annotations
@@ -42,14 +44,27 @@ def _load_toml(path: Path) -> dict[str, object]:
 def load_config(path: Path | None = None) -> AppConfig:
     """Load configuration from disk.
 
-    Lookup order:
-    1. ``ZOP_CONFIG`` env var (explicit override path)
-    2. ``<config_dir>/zop/config.toml`` (default location)
+    Lookup order (first existing file wins):
+    1. explicit ``path`` argument
+    2. ``ZOP_CONFIG`` env var (explicit override)
+    3. platform-specific user config dir (``platformdirs``: on Windows
+       ``%LOCALAPPDATA%\\zop``, on macOS ``~/Library/Application Support/zop``,
+       on Linux ``~/.config/zop``)
+    4. ``~/.config/zop/config.toml`` fallback (Unix convention, cross-platform)
     """
-    if path is None:
-        path = Path(os.environ["ZOP_CONFIG"]) if "ZOP_CONFIG" in os.environ else None
-
-    data = _load_toml(path) if path is not None else _load_toml(CONFIG_FILE)
+    if path is not None:
+        data = _load_toml(path)
+    else:
+        candidates: list[Path] = []
+        if "ZOP_CONFIG" in os.environ:
+            candidates.append(Path(os.environ["ZOP_CONFIG"]))
+        candidates.append(CONFIG_FILE)
+        candidates.append(Path.home() / ".config" / "zop" / "config.toml")
+        data = {}
+        for candidate in candidates:
+            if candidate.exists():
+                data = _load_toml(candidate)
+                break
 
     # Flat schema: [zotero] section.
     z = data.get("zotero", {}) if isinstance(data, dict) else {}

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/models/item.py

@@ -2,11 +2,26 @@
 
 from __future__ import annotations
 
+import re
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from zop.models.common import ID_PATTERN, ItemType
 
 
+def parse_year(date: str | None) -> int | None:
+    """Extract a 4-digit year from a Zotero date string, else None.
+
+    Zotero stores dates as free-form strings ("2024-05-01", "May 2024",
+    "2024-11-07 2024-11-07", ...). Single source of truth for year parsing —
+    both the read path (Item.year) and the export path go through it.
+    """
+    if date is None:
+        return None
+    match = re.search(r"\d{4}", date)
+    return int(match.group(0)) if match else None
+
+
 class ItemSummary(BaseModel):
     """Minimal item info (used for list views)."""
 

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/services/collections.py

@@ -11,6 +11,7 @@ This layer:
 from __future__ import annotations
 
 import asyncio
+import re
 from collections.abc import Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -24,6 +25,7 @@ from zop.core.errors import (
     ZopError,
 )
 from zop.models.collection import Collection, CollectionTree
+from zop.models.common import ID_PATTERN
 
 
 @dataclass
@@ -171,13 +173,17 @@ class CollectionsService:
         *,
         parent: str | None = None,
     ) -> Collection:
-        """Create one collection. `parent` is the parent NAME."""
+        """Create one collection.
+
+        ``parent`` may be a collection KEY (8-char) or NAME. KEY is used
+        directly; NAME is resolved locally, then (if not yet synced, e.g.
+        a just-created parent) via the Web API.
+        """
         api = self._require_api()
-        payload: dict[str, object] = {"name": name}
-        if parent:
-            p = self.resolve(parent)
-            payload["parentCollection"] = p.key
         async with api:
+            payload: dict[str, object] = {"name": name}
+            if parent:
+                payload["parentCollection"] = await self._resolve_parent(api, parent)
             result = await api.create_collections([payload])
         if not result:
             raise ZopError(f"Failed to create '{name}' (empty response)")
@@ -189,6 +195,25 @@ class CollectionsService:
             version=r["version"],
         )
 
+    async def _resolve_parent(self, api: ZoteroApi, parent: str) -> str:
+        """Resolve a parent reference (KEY or NAME) to a collection key.
+
+        KEY is used as-is. NAME is looked up locally first, then via the
+        Web API so a just-created parent (not yet in local SQLite) works.
+        """
+        if re.fullmatch(ID_PATTERN, parent):
+            return parent
+        try:
+            return self.resolve(parent).key
+        except NotFoundError:
+            remote = await api.list_collections()
+            for coll in remote:
+                if coll.get("data", {}).get("name") == parent:
+                    key = coll.get("key")
+                    if key:
+                        return str(key)
+            raise NotFoundError(f"No collection named '{parent}' (local or remote)") from None
+
     async def create_many(self, plan: list[PlanNode]) -> list[Collection]:
         """Create all collections in a validated plan (batched POST, topologically ordered).
 
@@ -261,7 +286,10 @@ class CollectionsService:
     async def delete(self, key: str) -> None:
         api = self._require_api()
         async with api:
-            await api.delete_collection(key)
+            # Zotero requires If-Unmodified-Since-Version for collection
+            # DELETE; fetch the current version first (mirrors ItemsService).
+            current = await api.get_collection(key)
+            await api.delete_collection(key, version=current["version"])
 
     async def reparent(
         self, key: str, new_parent: str | None, *, version: int | None = None
@@ -274,6 +302,9 @@ class CollectionsService:
         else:
             parent_key = self.resolve(new_parent).key
         async with api:
+            if version is None:
+                current = await api.get_collection(key)
+                version = current["version"]
             r = await api.update_collection(key, parent_key=parent_key, version=version)
         return Collection(
             key=r["key"],
@@ -322,5 +353,33 @@ class CollectionsService:
 
         return ok, fetch_failures + move_failures
 
+    async def execute_assignments(
+        self,
+        assignments: list[tuple[str, str]],
+        created_by_name: dict[str, str],
+    ) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]:
+        """Move items into their target collections after plan creation.
+
+        Reuses move_items (API GET + bounded-concurrent PATCH), so it works
+        even though the newly-created collections aren't in local SQLite
+        yet — target keys come from create_many's response, not the snapshot.
+        Returns (done, failed) as lists of (item_key, coll_key_or_error).
+        """
+        by_coll: dict[str, list[str]] = {}
+        unresolved: list[str] = []
+        for item_key, coll_name in assignments:
+            coll_key = created_by_name.get(coll_name)
+            if coll_key is None:
+                unresolved.append(item_key)
+                continue
+            by_coll.setdefault(coll_key, []).append(item_key)
+        done: list[tuple[str, str]] = []
+        failed: list[tuple[str, str]] = [(it, "collection not created") for it in unresolved]
+        for coll_key, items in by_coll.items():
+            ok, fails = await self.move_items(items, coll_key)
+            done.extend((it, coll_key) for it in ok)
+            failed.extend((it, str(e)) for it, e in fails)
+        return done, failed
+
 
 __all__ = ["CollectionsService", "PlanNode", "PlanReport"]

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/services/export.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 from zop.adapters.sqlite_reader import SqliteReader
 from zop.core.errors import ZopError
-from zop.models.item import Item
+from zop.models.item import Item, parse_year
 
 
 class ExportService:
@@ -103,10 +103,8 @@ def _escape_bibtex(s: str) -> str:
 
 
 def _extract_year(date: str | None) -> str:
-    if date is None:
-        return ""
-    m = re.search(r"\d{4}", date)
-    return m.group(0) if m else ""
+    year = parse_year(date)
+    return str(year) if year is not None else ""
 
 
 def _make_bibtex_key(item: Item) -> str:

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/services/items.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 from pathlib import Path
+from typing import Any
 
 from zop.adapters.sqlite_reader import SqliteReader
 from zop.adapters.zotero_api import ApiCreds, ZoteroApi
 from zop.core.errors import AuthError, NotFoundError, ZopError
-from zop.models.item import Item, ItemSummary
+from zop.models.common import ItemType
+from zop.models.item import Item, ItemSummary, parse_year
 
 
 class ItemsService:
@@ -125,7 +127,7 @@ class ItemsService:
             created = await api.create_items([payload])
         if not created:
             raise ZopError(f"DOI '{doi}' not found or rejected by server")
-        return self.get(created[0]["key"])
+        return await self._item_after_create(created[0])
 
     async def add_many(self, dois: Sequence[str]) -> list[Item]:
         """Add multiple items by DOI in a single batched POST."""
@@ -136,7 +138,43 @@ class ItemsService:
         ]
         async with api:
             created = await api.create_items(payload)
-        return [self.get(c["key"]) for c in created if c.get("key")]
+        return [await self._item_after_create(c) for c in created if c.get("key")]
+
+    async def _item_after_create(self, created: dict[str, Any]) -> Item:
+        """Return the created item: local DB if synced, else from API response.
+
+        A just-created item is not in local SQLite until Zotero syncs it
+        (BUG-9), so a strict local read would falsely report failure while
+        the item already exists server-side. Prefer local; fall back to the
+        API response so the caller gets the new key without a false error.
+        """
+        key = created.get("key")
+        if not key:
+            raise ZopError("Server created item but returned no key")
+        try:
+            return self._reader.get_item(str(key))
+        except NotFoundError:
+            return self._item_from_api_response(created)
+
+    def _item_from_api_response(self, created: dict[str, Any]) -> Item:
+        """Build a best-effort Item from a create_items API response.
+
+        Fields absent from the response (creators, etc.) are left empty;
+        they populate after Zotero syncs the new item to local SQLite.
+        """
+        data = created.get("data")
+        if not isinstance(data, dict):
+            data = {}
+        date_str = str(data["date"]) if data.get("date") else None
+        return Item(
+            key=str(created["key"]),
+            item_type=ItemType(str(data.get("itemType", ""))),
+            title=str(data.get("title", "")),
+            doi=str(data["DOI"]) if data.get("DOI") else None,
+            url=str(data["url"]) if data.get("url") else None,
+            date=date_str,
+            year=parse_year(date_str),
+        )
 
 
 __all__ = ["ItemsService"]

{zop_cli-0.2.0 → zop_cli-0.2.1}/src/zop/services/pdf.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TypedDict
+from typing import Any, TypedDict
 
 from pypdf import PdfReader
 
@@ -20,6 +20,41 @@ class OutlineEntry(TypedDict):
     depth: int
 
 
+def _resolve_page_number(reader: PdfReader, dest: Any) -> int | None:
+    """Resolve a 1-indexed page number for an outline destination.
+
+    Tries ``get_destination_page_number`` directly, then falls back to
+    named destinations (whose ``/Dest`` is a name string rather than an
+    explicit page array — the direct method returns None for those).
+    """
+    try:
+        num = reader.get_destination_page_number(dest)
+    except Exception:
+        num = None
+    if num is not None:
+        return num + 1
+    # Named-destination fallback: resolve the name, then its page.
+    target: object = None
+    get = getattr(dest, "get", None)
+    if callable(get):
+        target = get("/Dest")
+        if target is None:
+            action = get("/A")
+            action_get = getattr(action, "get", None)
+            if callable(action_get):
+                target = action_get("/D")
+    if isinstance(target, str):
+        named = reader.named_destinations.get(target)
+        if named is not None:
+            try:
+                num = reader.get_destination_page_number(named)
+            except Exception:
+                num = None
+            if num is not None:
+                return num + 1
+    return None
+
+
 class PdfService:
     """PDF operations: read text, extract outline."""
 
@@ -74,11 +109,7 @@ class PdfService:
                     title = str(raw_title.get("/Title", ""))
                 elif raw_title is not None:
                     title = str(raw_title)
-                try:
-                    raw_page = reader.get_destination_page_number(item)  # type: ignore[arg-type]
-                    page_num: int | None = raw_page + 1 if raw_page is not None else None
-                except Exception:
-                    page_num = None
+                page_num = _resolve_page_number(reader, item[0])
                 out.append(
                     {"section": len(out) + 1, "title": title, "page": page_num, "depth": depth}
                 )