architecture: try clean architecture pattern in feedbin subproject

Author: ooloth

cli.py

@@ -14,7 +14,7 @@
 
 import typer
 
-import feedbin.cli as feedbin_cli
+import feedbin.adapters.cli as feedbin_cli
 import modem.restart as modem_cli
 
 app = typer.Typer(no_args_is_help=True)

utils/cli.py common/cli.py

@@ -1,3 +1,16 @@
+"""
+To avoid ever exposing the secrets used by the scripts in this repo as plain text (e.g. in a local `.env` file), they
+are stored in 1Password and referenced by their location in the vault the 1Password service account has access to.
+
+When running these scripts locally, I'm prompted by the 1Password CLI to authenticate with my fingerprint. To support
+running these scripts via GitHub Actions workflows, an OP_SERVICE_ACCOUNT_TOKEN repository secret is needed to allow
+the 1Password CLI to authenticate the service account user used in that environment.
+
+Docs:
+ - https://developer.1password.com/docs/cli/secret-reference-syntax/
+ - https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository
+"""
+
 import subprocess
 
 # Docs (service accounts):

utils/logs.py common/logs.py

@@ -3,8 +3,8 @@
 from sendgrid.helpers.mail import Mail  # type: ignore
 from sendgrid.sendgrid import SendGridAPIClient  # type: ignore
 
-from op.secrets import get_secret
-from utils.logs import log
+from common.logs import log
+from common.secrets import get_secret
 
 OP_ITEM = "SendGrid"
 OP_FIELD = "api key"

op/secrets.py common/secrets.py

@@ -1,5 +1,6 @@
 """
 Core functionality for interacting with all Feedbin API endpoints.
+
 """
 
 from dataclasses import dataclass
@@ -8,7 +9,7 @@
 
 import requests
 
-from op.secrets import get_secret
+from common.secrets import get_secret
 
 API = "https://api.feedbin.com/v2"
 
@@ -46,17 +47,59 @@ def make_request(method: HTTPMethod, args: RequestArgs) -> requests.Response:
     """
     Make an HTTP request to the Feedbin API.
 
+    Since the possible status codes (and their explanations) vary by endpoint, we raise them at this base level
+    and catch them one level up in the endpoint-specific API helper functions.
+
     TODO:
-     - expect different request args based on the method?
+     - Expect different request args for GET vs POST methods?
     """
-    return requests.request(
+    response = requests.request(
         method.value,
         args.url,
         json=args.json,
         params=args.params,
         headers=args.headers,
         auth=_get_auth(),
     )
+    response.raise_for_status()
+    return response
+
+
+def parse_link_header(link_header: str) -> dict[str, str]:
+    """
+    Parse the Link header to extract URLs for pagination.
+
+    Docs:
+     - https://github.com/feedbin/feedbin-api?tab=readme-ov-file#pagination
+    """
+    links = {}
+    for link in link_header.split(","):
+        parts = link.split(";")
+        url = parts[0].strip()[1:-1]
+        rel = parts[1].strip().split("=")[1].strip('"')
+        links[rel] = url
+    return links
+
+
+def make_paginated_request(request_args: RequestArgs) -> list[dict[str, Any]]:
+    """
+    Fetch all pages of results for a paginated request.
+
+    Docs:
+     - https://github.com/feedbin/feedbin-api?tab=readme-ov-file#pagination
+    """
+    all_results = []
+    while request_args.url:
+        response = make_request(HTTPMethod.GET, request_args)
+        all_results.extend(response.json())
+        link_header = response.headers.get("Link")
+        if link_header:
+            links = parse_link_header(link_header)
+            request_args.url = links.get("next", "")
+        else:
+            request_args.url = ""
+
+    return all_results
 
 
 class FeedbinError(Exception):

notifications/sendgrid.py common/sendgrid.py

@@ -0,0 +1,68 @@
+"""
+Helper functions for Feedbin's entries endpoint.
+
+Docs:
+ - https://github.com/feedbin/feedbin-api/blob/master/content/entries.md#get-v2feeds203entriesjson
+"""
+
+from pydantic import BaseModel
+from requests import HTTPError
+
+from common.logs import log
+from feedbin.adapters.api import (
+    API,
+    ForbiddenError,
+    NotFoundError,
+    RequestArgs,
+    UnexpectedError,
+    make_paginated_request,
+)
+
+
+class Entry(BaseModel):
+    title: str
+    author: str
+    url: str
+    feed_id: int
+    id: int
+
+
+def get_feed_entries(
+    feed_id: int,
+    *,
+    read: bool | None = None,
+    starred: bool | None = None,
+) -> list[Entry]:
+    """
+    Get all entries for a feed.
+
+    Params:
+     - read: Filter by read status. Options: True, False, None.
+     - starred: Filter by starred status. Options: True, False, None.
+
+    TODO: accept a site_url and look up the feed_id internally?
+    """
+    request_args = RequestArgs(
+        url=f"{API}/feeds/{feed_id}/entries.json",
+        params={"read": read, "starred": starred},
+    )
+
+    try:
+        log.info(f"Feedbin: getting entries for feed {feed_id}")
+
+        all_entries = make_paginated_request(request_args)
+        log.debug(f"🔍 all_entries: {all_entries}")
+
+        parsed_entries = [Entry(**entry) for entry in all_entries]
+        log.debug(f"🔍 parsed_entries: {parsed_entries}")
+
+        return parsed_entries
+        # response = make_request(HTTPMethod.GET, request_args)
+    except HTTPError as e:
+        match e.response.status_code:
+            case 403:
+                raise ForbiddenError("Feedbin: you are not subscribed to feed {feed_id}")
+            case 404:
+                raise NotFoundError("Feedbin: no subscriptions found")
+            case _:
+                raise UnexpectedError("Feedbin: unexpected error while getting subscriptions")

feedbin/api/__init__.py feedbin/adapters/api/__init__.py

@@ -7,7 +7,8 @@
 
 from pydantic import BaseModel
 
-from feedbin.api import (
+from common.logs import log
+from feedbin.adapters.api import (
     API,
     FeedbinError,
     ForbiddenError,
@@ -17,7 +18,6 @@
     UnexpectedError,
     make_request,
 )
-from utils.logs import log
 
 
 class Subscription(BaseModel):

feedbin/adapters/api/entries.py

@@ -0,0 +1,40 @@
+"""
+Helper functions for Feedbin's unread entries endpoint.
+
+Docs:
+ - https://github.com/feedbin/feedbin-api/blob/master/content/unread-entries.md
+"""
+
+from common.logs import log
+from feedbin.adapters.api import API, HTTPMethod, RequestArgs, UnexpectedError, make_request
+
+
+def create_unread_entries(entry_ids: list[int]) -> list[int]:
+    """
+    Mark up to 1,000 entry IDs as unread.
+
+    The response will contain all of the entry_ids that were successfully marked as unread.
+    If any IDs that were sent are not returned in the response, it usually means the user
+    no longer has access to the feed the entry belongs to.
+    """
+    request_args = RequestArgs(
+        url=f"{API}/unread-entries.json",
+        json={"unread_entries": entry_ids},
+        headers={"Content-Type": "application/json; charset=utf-8"},
+    )
+
+    log.info(f"Marking {len(entry_ids)} entries as unread")
+    response = make_request(HTTPMethod.POST, request_args)
+
+    match response.status_code:
+        case 200:
+            entry_ids_marked_as_unread = response.json()
+            log.info(f"Marked {len(entry_ids_marked_as_unread)} entries as unread")
+
+            entry_ids_not_marked_as_unread = set(entry_ids) - set(entry_ids_marked_as_unread)
+            if entry_ids_not_marked_as_unread:
+                log.warning(f"Failed to mark the following entries as unread: {entry_ids_not_marked_as_unread}")
+
+            return entry_ids_marked_as_unread
+        case _:
+            raise UnexpectedError("Unexpected error while marking entries as unread")

feedbin/api/subscriptions.py feedbin/adapters/api/subscriptions.py

@@ -0,0 +1,35 @@
+"""
+CLI adapter for Feedbin. All typer commands should be defined in this module.
+"""
+
+from typing import Annotated
+
+import typer
+
+from common.cli import DryRun
+from feedbin.adapters.api.entries import get_feed_entries
+from feedbin.application.add_subscription import add_subscription
+from feedbin.application.list_subscriptions import list_subscriptions
+from feedbin.application.mark_entries_unread import mark_entries_unread
+
+subscriptions_app = typer.Typer(no_args_is_help=True)
+entries_app = typer.Typer(no_args_is_help=True)
+
+app = typer.Typer(no_args_is_help=True)
+app.add_typer(subscriptions_app, name="subscriptions")
+app.add_typer(entries_app, name="entries")
+
+
+MarkUnread = Annotated[bool, typer.Option("--unread", "-u", help="Mark backlog unread")]
+
+
+@app.command("add", no_args_is_help=True)
+def add(url: str, mark_backlog_unread: MarkUnread = False, dry_run: DryRun = False) -> None:
+    add_subscription(url, mark_backlog_unread=mark_backlog_unread, dry_run=dry_run)
+
+
+subscriptions_app.command(name="list")(list_subscriptions)
+entries_app.command(name="mark-unread", no_args_is_help=True)(mark_entries_unread)
+entries_app.command(name="list", no_args_is_help=True)(get_feed_entries)
+
+# michaeluloth.com = feed_id: 2338770

feedbin/adapters/api/unread_entries.py

@@ -1,13 +1,17 @@
+# TODO: move all "typer" usage to feedbin.adapters.cli
+
 import os
 from typing import Annotated
 
 import rich
 import typer
 
-from feedbin.api import NotFoundError, UnexpectedError
-from feedbin.api.subscriptions import FeedOption, MultipleChoicesError, Subscription, create_subscription
-from utils.cli import DryRun
-from utils.logs import log
+from common.cli import DryRun
+from common.logs import log
+from feedbin.adapters.api import NotFoundError, UnexpectedError
+from feedbin.adapters.api.entries import get_feed_entries
+from feedbin.adapters.api.subscriptions import FeedOption, MultipleChoicesError, Subscription, create_subscription
+from feedbin.application.mark_entries_unread import mark_entries_unread
 
 app = typer.Typer(no_args_is_help=True)
 
@@ -55,7 +59,7 @@ def subscribe_to_feed(url: str) -> Subscription:
 Unread = Annotated[bool, typer.Option("--unread", "-u", help="Mark backlog unread")]
 
 
-def main(url: str, mark_backlog_unread: Unread = False, dry_run: DryRun = False) -> None:
+def add_subscription(url: str, mark_backlog_unread: Unread = False, dry_run: DryRun = False) -> None:
     dry_run = os.getenv("DRY_RUN") == "true" or dry_run
 
     typer.confirm(f"🔖 Subscribe to '{url}'?", abort=True)
@@ -67,13 +71,21 @@ def main(url: str, mark_backlog_unread: Unread = False, dry_run: DryRun = False)
     new_subscription = subscribe_to_feed(url)
     log.debug(f"🔍 new_subscription: {new_subscription}")
 
-    mark_unread = typer.confirm("🔖 Mark backlog unread?", default=mark_backlog_unread)
+    mark_backlog_unread = typer.confirm("🔖 Mark backlog unread?", default=mark_backlog_unread)
 
-    if not mark_unread:
+    if not mark_backlog_unread:
         rich.print("👋 You're all set!")
         typer.Exit()
 
-    log.info("🔖 Marking backlog as unread")
+    log.info("🔖 Getting all entries")
+    entries = get_feed_entries(new_subscription.feed_id)
+    log.debug(f"🔍 entries: {entries}")
+
+    entry_ids = [entry.id for entry in entries]
+    log.debug(f"🔍 entry_ids: {entry_ids}")
+
+    log.info("🔖 Marking all entries as unread")
+    mark_entries_unread(entry_ids)
     # TODO: get all entry ids for this subscription via get_feed_entries
     # TODO: mark all entries as unread via https://github.com/feedbin/feedbin-api/blob/master/content/unread-entries.md#create-unread-entries-mark-as-unread