feat(readwise): add support for adding tags to the highlight

src/ridiwise/api/readwise.py

@@ -1,20 +1,25 @@
 import json
-from typing import Optional, TypedDict
+from typing import Literal, Optional, TypedDict
 
 import httpx
 
 from ridiwise.api.base_client import BaseClient, HTTPTokenAuth
 
+# https://readwise.io/api_deets
 API_BASE_URL = 'https://readwise.io/api/v2'
 
 
-class CreateHighlight(TypedDict, total=False):
+type BookCategory = Literal['books', 'articles', 'tweets', 'podcasts']
+type HightlightLocationType = Literal['page', 'order', 'time_offset']
+
+
+class CreateHighlightRequestItem(TypedDict, total=False):
     text: str
     title: str
     author: Optional[str]
-    category: Optional[str]
-    location: Optional[str]
-    location_type: Optional[str]
+    category: Optional[BookCategory]
+    location: Optional[int]
+    location_type: Optional[HightlightLocationType]
     highlighted_at: Optional[str]
     source_url: Optional[str]
     source_type: Optional[str]
@@ -23,6 +28,37 @@ class CreateHighlight(TypedDict, total=False):
     highlight_url: Optional[str]
 
 
+class CreateHighlightsRequest(TypedDict):
+    highlights: list[CreateHighlightRequestItem]
+
+
+class CreateHighlightResponseItem(TypedDict):
+    id: int
+    title: Optional[str]
+    author: Optional[str]
+    category: Optional[BookCategory]
+    source: Optional[str]
+    num_highlights: int
+    last_highlight_at: Optional[str]
+    updated: str
+    cover_image_url: Optional[str]
+    highlights_url: Optional[str]
+    source_url: Optional[str]
+    modified_highlights: list[int]
+
+
+type CreateHighlightsResponse = list[CreateHighlightResponseItem]
+
+
+class CreateHighlightTagRequest(TypedDict):
+    name: str
+
+
+class CreateHighlightTagResponse(TypedDict):
+    id: int
+    name: str
+
+
 class ReadwiseClient(BaseClient):
     base_url = API_BASE_URL
     provider = 'readwise'
@@ -48,12 +84,27 @@ def validate_token(self):
 
     def create_highlights(
         self,
-        highlights: list[CreateHighlight],
-    ):
-        payload = {'highlights': highlights}
+        highlights: list[CreateHighlightRequestItem],
+    ) -> CreateHighlightsResponse:
+        payload: CreateHighlightsRequest = {'highlights': highlights}
 
         self.logger.debug(json.dumps(payload, indent=2, ensure_ascii=False))
 
         response = self.client.post('/highlights/', auth=self.auth, json=payload)
         response.raise_for_status()
         return response.json()
+
+    def create_highlight_tag(
+        self,
+        highlight_id: int,
+        tag: str,
+    ) -> CreateHighlightTagResponse:
+        payload: CreateHighlightTagRequest = {'name': tag}
+
+        response = self.client.post(
+            f'/highlights/{highlight_id}/tags/',
+            auth=self.auth,
+            json=payload,
+        )
+        response.raise_for_status()
+        return response.json()

src/ridiwise/cmd/sync/main.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 import typer
 from typing_extensions import Annotated
 
@@ -28,6 +30,12 @@ def readwise(
             help='Readwise.io API token. https://readwise.io/access_token',
         ),
     ],
+    tags: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help='Tags to attach to the highlights. Multiple tags can be provided.',
+        ),
+    ] = None,
 ):
     """
     Sync Ridibooks book notes to Readwise.io.
@@ -54,7 +62,7 @@ def readwise(
         }
 
         for book in books:
-            readwise_client.create_highlights(
+            highlights_response = readwise_client.create_highlights(
                 highlights=[
                     {
                         'text': note['highlighted_text'],
@@ -65,13 +73,24 @@ def readwise(
                         'highlighted_at': note['created_date'].isoformat(),
                         'note': note['memo'],
                         'source_url': book['book_url'],
-                        'highlight_url': f'{book["book_notes_url"]}#annotation_{note["id"]}',  # noqa: E501 pylint: disable=line-too-long
+                        'highlight_url': (
+                            f'{book["book_notes_url"]}#annotation_{note["id"]}'
+                        ),
                         'image_url': book['book_cover_image_url'],
                     }
                     for note in book['notes']
                 ]
             )
 
+            modified_highlight_ids = highlights_response[0]['modified_highlights']
+
+            if tags:
+                for highlight_id, tag in zip(modified_highlight_ids, tags):
+                    readwise_client.create_highlight_tag(
+                        highlight_id=highlight_id,
+                        tag=tag,
+                    )
+
             result_count['books'] += 1
             result_count['highlights'] += len(book['notes'])