From 5649adcedc8941250cd93105507696bba871aaab Mon Sep 17 00:00:00 2001
From: Oleh Paduchak <opaduchak@exoft.net>
Date: Thu, 8 Aug 2024 17:51:41 +0300
Subject: [PATCH 1/2] added citation interface proposal

---
 addon_toolkit/interfaces/citation.py | 85 ++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 addon_toolkit/interfaces/citation.py

diff --git a/addon_toolkit/interfaces/citation.py b/addon_toolkit/interfaces/citation.py
new file mode 100644
index 00000000..08844920
--- /dev/null
+++ b/addon_toolkit/interfaces/citation.py
@@ -0,0 +1,85 @@
+import dataclasses
+import typing
+from enum import (
+    Enum,
+    auto,
+)
+
+
+__all__ = (
+    "ItemResult",
+    "ItemSampleResult",
+    "CitationConfig",
+    "ItemType",
+    "RootItemResult",
+    "CitationServiceInterface",
+    "CitationAddonImp",
+)
+
+from addon_toolkit import (
+    AddonCapabilities,
+    AddonImp,
+    BaseAddonInterface,
+    immediate_operation,
+)
+from addon_toolkit.constrained_network.http import HttpRequestor
+
+
+@dataclasses.dataclass(frozen=True)
+class CitationConfig:
+    external_api_url: str
+    connected_root_id: str | None = None
+    external_account_id: str | None = None
+
+
+class ItemType(Enum):
+    DOCUMENT = auto()
+    COLLECTION = auto()
+
+
+@dataclasses.dataclass(slots=True)
+class RootItemResult:
+    item_id: int
+    item_name: str
+    item_type: ItemType
+    item_path: typing.Optional[typing.List[str]] = None
+
+
+@dataclasses.dataclass
+class ItemResult(RootItemResult, slots=True):
+    csl: dict | None = None
+
+
+@dataclasses.dataclass
+class ItemSampleResult:
+    items: typing.List[RootItemResult]
+    total_count: typing.Optional[int] = None
+    next_sample_cursor: str | None = None
+    prev_sample_cursor: str | None = None
+
+
+# TODO: Merge My library and documents pickers into one picker (Zotero)
+# TODO: Migrate CSL compilation to backend
+
+
+class CitationServiceInterface(BaseAddonInterface):
+
+    @immediate_operation(capability=AddonCapabilities.ACCESS)
+    def list_root_collections(self) -> ItemSampleResult:
+        """Lists directories (or collections) inside root"""
+
+    @immediate_operation(capability=AddonCapabilities.ACCESS)
+    def list_collection_items(
+        self, collection_id: str, filter_items: ItemType | None = None
+    ) -> ItemSampleResult:
+        """Lists directories (or collections) and sources (books) inside root"""
+
+
+@dataclasses.dataclass(frozen=True)
+class CitationAddonImp(AddonImp):
+    """base class for storage addon implementations"""
+
+    ADDON_INTERFACE = CitationServiceInterface
+
+    config: CitationConfig
+    network: HttpRequestor

From d7b06e2609f39d31bc914cd7a13ff64a2fb9e0da Mon Sep 17 00:00:00 2001
From: Oleh Paduchak <opaduchak@exoft.net>
Date: Fri, 9 Aug 2024 12:57:02 +0300
Subject: [PATCH 2/2] merged ItemResult and RootItemResult

---
 addon_toolkit/interfaces/citation.py | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/addon_toolkit/interfaces/citation.py b/addon_toolkit/interfaces/citation.py
index 08844920..b4e6a172 100644
--- a/addon_toolkit/interfaces/citation.py
+++ b/addon_toolkit/interfaces/citation.py
@@ -7,11 +7,10 @@
 
 
 __all__ = (
-    "ItemResult",
     "ItemSampleResult",
     "CitationConfig",
     "ItemType",
-    "RootItemResult",
+    "ItemResult",
     "CitationServiceInterface",
     "CitationAddonImp",
 )
@@ -25,7 +24,7 @@
 from addon_toolkit.constrained_network.http import HttpRequestor
 
 
-@dataclasses.dataclass(frozen=True)
+@dataclasses.dataclass(frozen=True, slots=True)
 class CitationConfig:
     external_api_url: str
     connected_root_id: str | None = None
@@ -38,21 +37,17 @@ class ItemType(Enum):
 
 
 @dataclasses.dataclass(slots=True)
-class RootItemResult:
+class ItemResult:
     item_id: int
     item_name: str
     item_type: ItemType
-    item_path: typing.Optional[typing.List[str]] = None
-
-
-@dataclasses.dataclass
-class ItemResult(RootItemResult, slots=True):
+    item_path: list[str] | None = None
     csl: dict | None = None
 
 
-@dataclasses.dataclass
+@dataclasses.dataclass(slots=True)
 class ItemSampleResult:
-    items: typing.List[RootItemResult]
+    items: list[ItemResult]
     total_count: typing.Optional[int] = None
     next_sample_cursor: str | None = None
     prev_sample_cursor: str | None = None