python-substack 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

substack/api.py

@@ -1,792 +1,835 @@
-"""
-
-API Wrapper
-
-"""
-
-import base64
-import json
-import logging
-import os
-from datetime import datetime
-from urllib.parse import unquote, urljoin
-
-import requests
-from requests.adapters import HTTPAdapter, Retry
-
-from substack.exceptions import SubstackAPIException, SubstackRequestException
-
-logger = logging.getLogger(__name__)
-
-__all__ = ["Api"]
-
-
-class Api:
-    """
-
-    A python interface into the Substack API
-
-    """
-
-    def __init__(
-        self,
-        email=None,
-        password=None,
-        cookies_path=None,
-        base_url=None,
-        publication_url=None,
-        debug=False,
-        cookies_string=None,
-    ):
-        """
-
-        To create an instance of the substack.Api class:
-            >>> import substack
-            >>> api = substack.Api(email="substack email", password="substack password")
-
-        Args:
-          email:
-          password:
-          cookies_path
-            To re-use your session without logging in each time, you can save your cookies to a json file and
-            then load them in the next session.
-            Make sure to re-save your cookies, as they do update over time.
-          cookies_string
-            To re-use your session without logging in each time, you can provide cookies as a semicolon-separated
-            string (e.g., "cookie1=value1; cookie2=value2"). This is useful when copying cookies from browser
-            developer tools.
-          base_url:
-            The base URL to use to contact the Substack API.
-            Defaults to https://substack.com/api/v1.
-        """
-        self.base_url = base_url or "https://substack.com/api/v1"
-
-        if debug:
-            logging.basicConfig()
-            logging.getLogger().setLevel(logging.DEBUG)
-
-        self._session = requests.Session()
-        retry = Retry(
-            total=4,
-            status=4,
-            backoff_factor=1,
-            status_forcelist=(429,),
-            allowed_methods=frozenset({"GET", "DELETE"}),
-            respect_retry_after_header=True,
-            raise_on_status=False,
-        )
-        adapter = HTTPAdapter(max_retries=retry)
-        self._session.mount("http://", adapter)
-        self._session.mount("https://", adapter)
-
-        # Load cookies from file if provided
-        # Helps with Captcha errors by reusing cookies from "local" auth, then switching to running code in the cloud
-        if cookies_path is not None:
-            with open(cookies_path) as f:
-                cookies = json.load(f)
-            self._session.cookies.update(cookies)
-
-        elif cookies_string is not None:
-            cookies = self._parse_cookies_string(cookies_string)
-            self._session.cookies.update(cookies)
-
-        elif email is not None and password is not None:
-            self.login(email, password)
-        else:
-            raise ValueError(
-                "Must provide email and password, cookies_path, or cookies_string to authenticate."
-            )
-
-        user_publication = None
-        # if the user provided a publication url, then use that
-        if publication_url:
-            import re
-
-            # Regular expression to extract subdomain name
-            match = re.search(r"https://(.*).substack.com", publication_url.lower())
-            subdomain = match.group(1) if match else None
-
-            user_publications = self.get_user_publications()
-            # search through publications to find the publication with the matching subdomain
-            for publication in user_publications:
-                if publication["subdomain"] == subdomain:
-                    # set the current publication to the users publication
-                    user_publication = publication
-                    break
-        else:
-            # get the users primary publication
-            user_publication = self.get_user_primary_publication()
-
-        # set the current publication to the users primary publication
-        self.change_publication(user_publication)
-
-    @staticmethod
-    def _parse_cookies_string(cookies_string: str) -> dict:
-        """
-        Parse a semicolon-separated cookie string into a dictionary.
-
-        Args:
-            cookies_string: A semicolon-separated string of cookies (e.g., "cookie1=value1; cookie2=value2")
-
-        Returns:
-            A dictionary of cookie name-value pairs
-        """
-        cookies = {}
-        for cookie_pair in cookies_string.split(";"):
-            cookie_pair = cookie_pair.strip()
-            if not cookie_pair:
-                continue
-            if "=" in cookie_pair:
-                key, value = cookie_pair.split("=", 1)
-                key = key.strip()
-                value = value.strip()
-                # URL decode the value (e.g., s%3A becomes s:)
-                value = unquote(value)
-                cookies[key] = value
-        return cookies
-
-    @staticmethod
-    def _normalize_tags(tags):
-        if tags is None:
-            return []
-        if isinstance(tags, str):
-            return [tags]
-        return [str(tag) for tag in tags]
-
-    def login(self, email, password) -> dict:
-        """
-
-        Login to the substack account.
-
-        Args:
-          email: substack account email
-          password: substack account password
-        """
-
-        response = self._session.post(
-            f"{self.base_url}/login",
-            json={
-                "captcha_response": None,
-                "email": email,
-                "for_pub": "",
-                "password": password,
-                "redirect": "/",
-            },
-        )
-
-        return Api._handle_response(response=response)
-
-    def signin_for_pub(self, publication):
-        """
-        Complete the signin process
-        """
-        response = self._session.get(
-            f"https://substack.com/sign-in?redirect=%2F&for_pub={publication['subdomain']}",
-        )
-        try:
-            output = Api._handle_response(response=response)
-        except SubstackRequestException as ex:
-            output = {}
-        return output
-
-    def change_publication(self, publication):
-        """
-        Change the publication URL
-        """
-        self.publication_url = urljoin(publication["publication_url"], "api/v1")
-
-        # sign-in to the publication
-        self.signin_for_pub(publication)
-
-    def export_cookies(self, path: str = "cookies.json"):
-        """
-        Export cookies to a json file.
-        Args:
-            path: path to the json file
-        """
-        cookies = self._session.cookies.get_dict()
-        with open(path, "w") as f:
-            json.dump(cookies, f)
-
-    @staticmethod
-    def _handle_response(response: requests.Response):
-        """
-
-        Internal helper for handling API responses from the Substack server.
-        Raises the appropriate exceptions when necessary; otherwise, returns the
-        response.
-
-        """
-
-        if not (200 <= response.status_code < 300):
-            raise SubstackAPIException(response.status_code, response.text)
-        try:
-            return response.json()
-        except ValueError:
-            raise SubstackRequestException("Invalid Response: %s" % response.text)
-
-    def get_user_id(self):
-        """
-
-        Returns:
-
-        """
-        profile = self.get_user_profile()
-        user_id = profile["id"]
-
-        return user_id
-
-    @staticmethod
-    def get_publication_url(publication: dict) -> str:
-        """
-        Gets the publication url
-
-        Args:
-            publication:
-        """
-        custom_domain = publication.get("custom_domain", None)
-        if not custom_domain and not publication.get("custom_domain_optional", None):
-            publication_url = f"https://{publication['subdomain']}.substack.com"
-        else:
-            publication_url = f"https://{custom_domain}"
-
-        return publication_url
-
-    def get_user_primary_publication(self):
-        """
-        Gets the users primary publication
-        """
-
-        profile = self.get_user_profile()
-        primary_publication = None
-
-        # Try old API format first (backward compatibility)
-        if (
-            "primaryPublication" in profile
-            and profile["primaryPublication"] is not None
-        ):
-            primary_publication = profile["primaryPublication"]
-        else:
-            # New API format: look for primary publication in publicationUsers
-            publication_users = profile.get("publicationUsers")
-            if publication_users is not None and len(publication_users) > 0:
-                # Find the publication where is_primary is True
-                for pub_user in publication_users:
-                    if pub_user.get("is_primary", False):
-                        primary_publication = pub_user.get("publication")
-                        if primary_publication:
-                            break
-
-                # If no primary found, use the first publication
-                if primary_publication is None:
-                    primary_publication = publication_users[0].get("publication")
-
-        if primary_publication is None:
-            raise SubstackRequestException(
-                "Could not find primary publication in profile"
-            )
-
-        primary_publication["publication_url"] = self.get_publication_url(
-            primary_publication
-        )
-
-        return primary_publication
-
-    def get_user_publications(self):
-        """
-        Gets the users publications
-        """
-
-        profile = self.get_user_profile()
-
-        # Loop through users "publicationUsers" list, and return a list
-        # of dictionaries of "name", and "subdomain", and "id"
-        user_publications = []
-        publication_users = profile.get("publicationUsers")
-
-        if publication_users is None:
-            # If publicationUsers is None, return empty list or try to construct from other fields
-            # This maintains backward compatibility while handling new API format
-            return user_publications
-
-        for publication in publication_users:
-            pub = publication.get("publication")
-            if pub is not None:
-                pub["publication_url"] = self.get_publication_url(pub)
-                user_publications.append(pub)
-
-        return user_publications
-
-    def get_user_profile(self):
-        """
-        Gets the users profile
-        """
-        response = self._session.get(f"{self.base_url}/user/profile/self")
-
-        return Api._handle_response(response=response)
-
-    def get_user_settings(self):
-        """
-        Get list of users.
-
-        Returns:
-
-        """
-        response = self._session.get(f"{self.base_url}/settings")
-
-        return Api._handle_response(response=response)
-
-    def get_publication_users(self):
-        """
-        Get list of users.
-
-        Returns:
-
-        """
-        response = self._session.get(f"{self.publication_url}/publication/users")
-
-        return Api._handle_response(response=response)
-
-    def get_publication_subscriber_count(self):
-        """
-        Get subscriber count.
-
-        Returns:
-
-        """
-        response = self._session.get(
-            f"{self.publication_url}/publication_launch_checklist"
-        )
-
-        data = Api._handle_response(response=response)
-        if "subscriberCount" in data:
-            return data["subscriberCount"]
-        return len(data["subscribers"])
-
-    def get_published_posts(
-        self, offset=0, limit=25, order_by="post_date", order_direction="desc"
-    ):
-        """
-        Get list of published posts for the publication.
-        """
-        response = self._session.get(
-            f"{self.publication_url}/post_management/published",
-            params={
-                "offset": offset,
-                "limit": limit,
-                "order_by": order_by,
-                "order_direction": order_direction,
-            },
-        )
-
-        return Api._handle_response(response=response)
-
-    def get_posts(self) -> dict:
-        """
-
-        Returns:
-
-        """
-        response = self._session.get(f"{self.base_url}/reader/posts")
-
-        return Api._handle_response(response=response)
-
-    def get_drafts(self, filter=None, offset=None, limit=None):
-        """
-
-        Args:
-            filter:
-            offset:
-            limit:
-
-        Returns:
-
-        """
-        response = self._session.get(
-            f"{self.publication_url}/drafts",
-            params={"filter": filter, "offset": offset, "limit": limit},
-        )
-        return Api._handle_response(response=response)
-
-    def get_draft(self, draft_id):
-        """
-        Gets a draft given it's id.
-
-        """
-        response = self._session.get(f"{self.publication_url}/drafts/{draft_id}")
-        return Api._handle_response(response=response)
-
-    def delete_draft(self, draft_id):
-        """
-
-        Args:
-            draft_id:
-
-        Returns:
-
-        """
-        response = self._session.delete(f"{self.publication_url}/drafts/{draft_id}")
-        return Api._handle_response(response=response)
-
-    def post_draft(self, body) -> dict:
-        """
-
-        Args:
-          body:
-
-        Returns:
-
-        """
-        response = self._session.post(f"{self.publication_url}/drafts", json=body)
-        return Api._handle_response(response=response)
-
-    def create_draft_from_markdown(
-        self,
-        title: str,
-        markdown: str,
-        subtitle: str = "",
-        audience: str = "everyone",
-        write_comment_permissions: str = "everyone",
-        search_engine_title: str = None,
-        search_engine_description: str = None,
-        slug: str = None,
-        draft_section_id: int = None,
-        tags=None,
-        prepublish: bool = False,
-        publish: bool = False,
-        send: bool = True,
-        share_automatically: bool = False,
-    ) -> dict:
-        from substack.post import Post
-
-        post = Post(
-            title=title,
-            subtitle=subtitle or "",
-            user_id=self.get_user_id(),
-            audience=audience,
-            write_comment_permissions=write_comment_permissions,
-        )
-        post.from_markdown(markdown, api=self)
-
-        draft = self.post_draft(post.get_draft())
-        draft_id = draft.get("id")
-
-        update_payload = {
-            "search_engine_title": search_engine_title,
-            "search_engine_description": search_engine_description,
-            "slug": slug,
-            "draft_section_id": draft_section_id,
-        }
-        update_payload = {
-            key: value for key, value in update_payload.items() if value is not None
-        }
-        if update_payload:
-            draft = self.put_draft(draft_id, **update_payload)
-
-        tags_result = None
-        tags_list = self._normalize_tags(tags)
-        if tags_list:
-            tags_result = self.add_tags_to_post(draft_id, tags_list)
-
-        prepublish_result = None
-        if prepublish:
-            prepublish_result = self.prepublish_draft(draft_id)
-
-        publish_result = None
-        if publish:
-            publish_result = self.publish_draft(
-                draft_id,
-                send=send,
-                share_automatically=share_automatically,
-            )
-
-        return {
-            "draft": draft,
-            "tags": tags_result,
-            "prepublish": prepublish_result,
-            "publish": publish_result,
-        }
-
-    def put_draft(self, draft, **kwargs) -> dict:
-        """
-
-        Args:
-            draft:
-            **kwargs:
-
-        Returns:
-
-        """
-        response = self._session.put(
-            f"{self.publication_url}/drafts/{draft}",
-            json=kwargs,
-        )
-        return Api._handle_response(response=response)
-
-    def prepublish_draft(self, draft) -> dict:
-        """
-
-        Args:
-            draft: draft id
-
-        Returns:
-
-        """
-
-        response = self._session.get(
-            f"{self.publication_url}/drafts/{draft}/prepublish"
-        )
-        return Api._handle_response(response=response)
-
-    def publish_draft(
-        self, draft, send: bool = True, share_automatically: bool = False
-    ) -> dict:
-        """
-
-        Args:
-            draft: draft id
-            send:
-            share_automatically:
-
-        Returns:
-
-        """
-        response = self._session.post(
-            f"{self.publication_url}/drafts/{draft}/publish",
-            json={"send": send, "share_automatically": share_automatically},
-        )
-        return Api._handle_response(response=response)
-
-    def schedule_draft(self, draft, draft_datetime: datetime) -> dict:
-        """
-
-        Args:
-            draft: draft id
-            draft_datetime: datetime to schedule the draft
-
-        Returns:
-
-        """
-        response = self._session.post(
-            f"{self.publication_url}/drafts/{draft}/scheduled_release",
-            json={"trigger_at": draft_datetime.isoformat()},
-        )
-        return Api._handle_response(response=response)
-
-    def unschedule_draft(self, draft) -> dict:
-        """
-
-        Args:
-            draft: draft id
-
-        Returns:
-
-        """
-        response = self._session.delete(
-            f"{self.publication_url}/drafts/{draft}/scheduled_release"
-        )
-        return Api._handle_response(response=response)
-
-    def get_image(self, image: str):
-        """
-
-        This method generates a new substack link that contains the image.
-
-        Args:
-            image: filepath or original url of image.
-
-        Returns:
-
-        """
-        if os.path.exists(image):
-            with open(image, "rb") as file:
-                image = b"data:image/jpeg;base64," + base64.b64encode(file.read())
-
-        response = self._session.post(
-            f"{self.publication_url}/image",
-            data={"image": image},
-        )
-        return Api._handle_response(response=response)
-
-    def add_tags_to_post(self, post_id: int, tag_names: list) -> dict:
-        """
-        Add multiple tags to a post.
-
-        Args:
-            post_id: The ID of the post to tag.
-            tag_names: A list of tag names to add.
-
-        Returns:
-            A dictionary with the results of applying all tags.
-        """
-        results = []
-        for tag_name in tag_names:
-            result = self.add_tag_to_post(post_id, tag_name)
-            results.append(result)
-        return {"tags_added": results}
-
-    def get_publication_post_tags(self) -> list:
-        """
-        Retrieve all post tags for the current publication.
-
-        Returns:
-            List of tag dicts as returned by Substack API.
-        """
-        response = self._session.get(f"{self.publication_url}/publication/post-tag")
-        return Api._handle_response(response=response)
-
-    def add_tag_to_post(self, post_id: int, tag_name: str) -> dict:
-        """
-        Add a tag to a post by first checking published tags and creating only if needed.
-
-        Args:
-            post_id: The ID of the post to tag.
-            tag_name: The name of the tag to add.
-
-        Returns:
-            The response from applying the tag to the post.
-        """
-        # Fetch existing publication tags first (avoid re-creating an already existing tag)
-        existing_tags = self.get_publication_post_tags() or []
-        existing_tag = next(
-            (tag for tag in existing_tags if tag.get("name") == tag_name),
-            None,
-        )
-
-        if existing_tag is not None:
-            tag_id = existing_tag["id"]
-        else:
-            create_tag_response = self._session.post(
-                f"{self.publication_url}/publication/post-tag",
-                json={"name": tag_name},
-            )
-            tag_data = Api._handle_response(create_tag_response)
-            tag_id = tag_data["id"]
-
-        apply_tag_response = self._session.post(
-            f"{self.publication_url}/post/{post_id}/tag/{tag_id}",
-        )
-        return Api._handle_response(apply_tag_response)
-
-    def get_categories(self):
-        """
-
-        Retrieve list of all available categories.
-
-        Returns:
-
-        """
-        response = self._session.get(f"{self.base_url}/categories")
-        return Api._handle_response(response=response)
-
-    def get_category(self, category_id, category_type, page):
-        """
-
-        Args:
-            category_id:
-            category_type:
-            page:
-
-        Returns:
-
-        """
-        response = self._session.get(
-            f"{self.base_url}/category/public/{category_id}/{category_type}",
-            params={"page": page},
-        )
-        return Api._handle_response(response=response)
-
-    def get_single_category(self, category_id, category_type, page=None, limit=None):
-        """
-
-        Args:
-            category_id:
-            category_type: paid or all
-            page: by default substack retrieves only the first 25 publications in the category. If this is left None,
-                  then all pages will be retrieved. The page size is 25 publications.
-            limit:
-        Returns:
-
-        """
-        if page is not None:
-            output = self.get_category(category_id, category_type, page)
-        else:
-            publications = []
-            page = 0
-            while True:
-                page_output = self.get_category(category_id, category_type, page)
-                publications.extend(page_output.get("publications", []))
-                if (
-                    limit is not None and limit <= len(publications)
-                ) or not page_output.get("more", False):
-                    publications = publications[:limit]
-                    break
-                page += 1
-            output = {
-                "publications": publications,
-                "more": page_output.get("more", False),
-            }
-        return output
-
-    def delete_all_drafts(self):
-        """
-
-        Returns:
-
-        """
-        response = None
-        while True:
-            drafts = self.get_drafts(filter="draft", limit=10, offset=0)
-            if len(drafts) == 0:
-                break
-            for draft in drafts:
-                response = self.delete_draft(draft.get("id"))
-        return response
-
-    def get_sections(self):
-        """
-        Get a list of the sections of your publication.
-
-        TODO: this is hacky but I cannot find another place where to get the sections.
-        Returns:
-
-        """
-        response = self._session.get(
-            f"{self.publication_url}/subscriptions",
-        )
-        content = Api._handle_response(response=response)
-        sections = [
-            p.get("sections")
-            for p in content.get("publications")
-            if p.get("hostname") in self.publication_url
-        ]
-        return sections[0]
-
-    def publication_embed(self, url):
-        """
-
-        Args:
-            url:
-
-        Returns:
-
-        """
-        return self.call("/publication/embed", "GET", url=url)
-
-    def call(self, endpoint, method, **params):
-        """
-
-        Args:
-            endpoint:
-            method:
-            **params:
-
-        Returns:
-
-        """
-        response = self._session.request(
-            method=method,
-            url=f"{self.publication_url}/{endpoint}",
-            params=params,
-        )
-        return Api._handle_response(response=response)
+"""
+
+API Wrapper
+
+"""
+
+import base64
+import json
+import logging
+import os
+from datetime import datetime
+from urllib.parse import unquote, urljoin
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+
+from substack.exceptions import SubstackAPIException, SubstackRequestException
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Api"]
+
+
+class Api:
+    """
+
+    A python interface into the Substack API
+
+    """
+
+    def __init__(
+        self,
+        email=None,
+        password=None,
+        cookies_path=None,
+        base_url=None,
+        publication_url=None,
+        debug=False,
+        cookies_string=None,
+        timeout=None,
+    ):
+        """
+
+        To create an instance of the substack.Api class:
+            >>> import substack
+            >>> api = substack.Api(email="substack email", password="substack password")
+
+        Args:
+          email:
+          password:
+          cookies_path
+            To re-use your session without logging in each time, you can save your cookies to a json file and
+            then load them in the next session.
+            Make sure to re-save your cookies, as they do update over time.
+          cookies_string
+            To re-use your session without logging in each time, you can provide cookies as a semicolon-separated
+            string (e.g., "cookie1=value1; cookie2=value2"). This is useful when copying cookies from browser
+            developer tools.
+          base_url:
+            The base URL to use to contact the Substack API.
+            Defaults to https://substack.com/api/v1.
+        """
+        self.base_url = base_url or "https://substack.com/api/v1"
+
+        if debug:
+            logging.basicConfig()
+            logging.getLogger().setLevel(logging.DEBUG)
+
+        self.timeout = timeout
+
+        self._session = requests.Session()
+        original_request = self._session.request
+
+        def _request_with_timeout(*args, **kwargs):
+            if kwargs.get("timeout") is None and self.timeout is not None:
+                kwargs["timeout"] = self.timeout
+            return original_request(*args, **kwargs)
+
+        self._session.request = _request_with_timeout
+
+        retry = Retry(
+            total=4,
+            status=4,
+            backoff_factor=1,
+            status_forcelist=(429,),
+            allowed_methods=frozenset({"GET", "DELETE"}),
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("http://", adapter)
+        self._session.mount("https://", adapter)
+
+        # Load cookies from file if provided
+        # Helps with Captcha errors by reusing cookies from "local" auth, then switching to running code in the cloud
+        if cookies_path is not None:
+            with open(cookies_path) as f:
+                cookies = json.load(f)
+            self._session.cookies.update(cookies)
+
+        elif cookies_string is not None:
+            cookies = self._parse_cookies_string(cookies_string)
+            self._session.cookies.update(cookies)
+
+        elif email is not None and password is not None:
+            self.login(email, password)
+        else:
+            raise ValueError(
+                "Must provide email and password, cookies_path, or cookies_string to authenticate."
+            )
+
+        user_publication = None
+        # if the user provided a publication url, then use that
+        if publication_url:
+            from urllib.parse import urlparse
+
+            # Normalize requested URL
+            parsed_req = urlparse(publication_url.lower())
+            req_hostname = parsed_req.hostname or parsed_req.path
+            # Strip trailing slashes and www.
+            req_hostname = req_hostname.strip("/").replace("www.", "", 1)
+
+            user_publications = self.get_user_publications()
+            for publication in user_publications:
+                pub_url = Api.get_publication_url(publication).lower()
+                parsed_pub = urlparse(pub_url)
+                pub_hostname = parsed_pub.hostname or parsed_pub.path
+                pub_hostname = pub_hostname.strip("/").replace("www.", "", 1)
+
+                if req_hostname == pub_hostname:
+                    user_publication = publication
+                    break
+
+            if user_publication is None:
+                raise SubstackRequestException(
+                    f"Requested publication is unavailable: {publication_url}"
+                )
+        else:
+            # get the users primary publication
+            user_publication = self.get_user_primary_publication()
+            if user_publication is None:
+                raise SubstackRequestException(
+                    "Could not find primary publication in profile"
+                )
+
+        # set the current publication to the users primary publication
+        self.change_publication(user_publication)
+
+    @staticmethod
+    def _parse_cookies_string(cookies_string: str) -> dict:
+        """
+        Parse a semicolon-separated cookie string into a dictionary.
+
+        Args:
+            cookies_string: A semicolon-separated string of cookies (e.g., "cookie1=value1; cookie2=value2")
+
+        Returns:
+            A dictionary of cookie name-value pairs
+        """
+        cookies = {}
+        for cookie_pair in cookies_string.split(";"):
+            cookie_pair = cookie_pair.strip()
+            if not cookie_pair:
+                continue
+            if "=" in cookie_pair:
+                key, value = cookie_pair.split("=", 1)
+                key = key.strip()
+                value = value.strip()
+                # URL decode the value (e.g., s%3A becomes s:)
+                value = unquote(value)
+                cookies[key] = value
+        return cookies
+
+    @staticmethod
+    def _normalize_tags(tags):
+        if tags is None:
+            return []
+        if isinstance(tags, str):
+            return [tags]
+        return [str(tag) for tag in tags]
+
+    def login(self, email, password) -> dict:
+        """
+
+        Login to the substack account.
+
+        Args:
+          email: substack account email
+          password: substack account password
+        """
+
+        response = self._session.post(
+            f"{self.base_url}/login",
+            json={
+                "captcha_response": None,
+                "email": email,
+                "for_pub": "",
+                "password": password,
+                "redirect": "/",
+            },
+        )
+
+        return Api._handle_response(response=response)
+
+    def signin_for_pub(self, publication):
+        """
+        Complete the signin process
+        """
+        response = self._session.get(
+            f"https://substack.com/sign-in?redirect=%2F&for_pub={publication['subdomain']}",
+        )
+        try:
+            output = Api._handle_response(response=response)
+        except SubstackRequestException as ex:
+            output = {}
+        return output
+
+    def change_publication(self, publication):
+        """
+        Change the publication URL
+        """
+        self.publication_url = urljoin(publication["publication_url"], "api/v1")
+
+        # sign-in to the publication
+        self.signin_for_pub(publication)
+
+    def export_cookies(self, path: str = "cookies.json"):
+        """
+        Export cookies to a json file.
+        Args:
+            path: path to the json file
+        """
+        cookies = self._session.cookies.get_dict()
+        with open(path, "w") as f:
+            json.dump(cookies, f)
+
+    @staticmethod
+    def _handle_response(response: requests.Response):
+        """
+
+        Internal helper for handling API responses from the Substack server.
+        Raises the appropriate exceptions when necessary; otherwise, returns the
+        response.
+
+        """
+
+        if not (200 <= response.status_code < 300):
+            raise SubstackAPIException(response.status_code, response.text)
+        try:
+            return response.json()
+        except ValueError:
+            raise SubstackRequestException("Invalid Response: %s" % response.text)
+
+    def get_user_id(self):
+        """
+
+        Returns:
+
+        """
+        profile = self.get_user_profile()
+        user_id = profile["id"]
+
+        return user_id
+
+    @staticmethod
+    def get_publication_url(publication: dict) -> str:
+        """
+        Gets the publication url
+
+        Args:
+            publication:
+        """
+        custom_domain = publication.get("custom_domain", None)
+        if not custom_domain and not publication.get("custom_domain_optional", None):
+            publication_url = f"https://{publication['subdomain']}.substack.com"
+        else:
+            publication_url = f"https://{custom_domain}"
+
+        return publication_url
+
+    def get_user_primary_publication(self):
+        """
+        Gets the users primary publication
+        """
+
+        profile = self.get_user_profile()
+        primary_publication = None
+
+        # Try old API format first (backward compatibility)
+        if (
+            "primaryPublication" in profile
+            and profile["primaryPublication"] is not None
+        ):
+            primary_publication = profile["primaryPublication"]
+        else:
+            # New API format: look for primary publication in publicationUsers
+            publication_users = profile.get("publicationUsers")
+            if publication_users is not None and len(publication_users) > 0:
+                # Find the publication where is_primary is True
+                for pub_user in publication_users:
+                    if pub_user.get("is_primary", False):
+                        primary_publication = pub_user.get("publication")
+                        if primary_publication:
+                            break
+
+                # If no primary found, use the first publication
+                if primary_publication is None:
+                    primary_publication = publication_users[0].get("publication")
+
+        if primary_publication is None:
+            raise SubstackRequestException(
+                "Could not find primary publication in profile"
+            )
+
+        primary_publication["publication_url"] = self.get_publication_url(
+            primary_publication
+        )
+
+        return primary_publication
+
+    def get_user_publications(self):
+        """
+        Gets the users publications
+        """
+
+        profile = self.get_user_profile()
+
+        # Loop through users "publicationUsers" list, and return a list
+        # of dictionaries of "name", and "subdomain", and "id"
+        user_publications = []
+        publication_users = profile.get("publicationUsers")
+
+        if publication_users is None:
+            # If publicationUsers is None, return empty list or try to construct from other fields
+            # This maintains backward compatibility while handling new API format
+            return user_publications
+
+        for publication in publication_users:
+            pub = publication.get("publication")
+            if pub is not None:
+                pub["publication_url"] = self.get_publication_url(pub)
+                user_publications.append(pub)
+
+        return user_publications
+
+    def get_user_profile(self):
+        """
+        Gets the users profile
+        """
+        response = self._session.get(f"{self.base_url}/user/profile/self")
+
+        return Api._handle_response(response=response)
+
+    def get_user_settings(self):
+        """
+        Get list of users.
+
+        Returns:
+
+        """
+        response = self._session.get(f"{self.base_url}/settings")
+
+        return Api._handle_response(response=response)
+
+    def get_publication_users(self):
+        """
+        Get list of users.
+
+        Returns:
+
+        """
+        response = self._session.get(f"{self.publication_url}/publication/users")
+
+        return Api._handle_response(response=response)
+
+    def get_publication_subscriber_count(self):
+        """
+        Get subscriber count.
+
+        Returns:
+
+        """
+        response = self._session.get(
+            f"{self.publication_url}/publication_launch_checklist"
+        )
+
+        data = Api._handle_response(response=response)
+        if "subscriberCount" in data:
+            return data["subscriberCount"]
+        return len(data["subscribers"])
+
+    def get_published_posts(
+        self, offset=0, limit=25, order_by="post_date", order_direction="desc"
+    ):
+        """
+        Get list of published posts for the publication.
+        """
+        response = self._session.get(
+            f"{self.publication_url}/post_management/published",
+            params={
+                "offset": offset,
+                "limit": limit,
+                "order_by": order_by,
+                "order_direction": order_direction,
+            },
+        )
+
+        return Api._handle_response(response=response)
+
+    def get_posts(self) -> dict:
+        """
+
+        Returns:
+
+        """
+        response = self._session.get(f"{self.base_url}/reader/posts")
+
+        return Api._handle_response(response=response)
+
+    def get_drafts(self, filter=None, offset=None, limit=None):
+        """
+
+        Args:
+            filter:
+            offset:
+            limit:
+
+        Returns:
+
+        """
+        response = self._session.get(
+            f"{self.publication_url}/drafts",
+            params={"filter": filter, "offset": offset, "limit": limit},
+        )
+        return Api._handle_response(response=response)
+
+    def get_draft(self, draft_id):
+        """
+        Gets a draft given it's id.
+
+        """
+        response = self._session.get(f"{self.publication_url}/drafts/{draft_id}")
+        return Api._handle_response(response=response)
+
+    def delete_draft(self, draft_id):
+        """
+
+        Args:
+            draft_id:
+
+        Returns:
+
+        """
+        response = self._session.delete(f"{self.publication_url}/drafts/{draft_id}")
+        return Api._handle_response(response=response)
+
+    def post_draft(self, body) -> dict:
+        """
+
+        Args:
+          body:
+
+        Returns:
+
+        """
+        response = self._session.post(f"{self.publication_url}/drafts", json=body)
+        return Api._handle_response(response=response)
+
+    def create_draft_from_markdown(
+        self,
+        title: str,
+        markdown: str,
+        subtitle: str = "",
+        audience: str = "everyone",
+        write_comment_permissions: str = "everyone",
+        search_engine_title: str = None,
+        search_engine_description: str = None,
+        slug: str = None,
+        draft_section_id: int = None,
+        tags=None,
+        prepublish: bool = False,
+        publish: bool = False,
+        send: bool = True,
+        share_automatically: bool = False,
+    ) -> dict:
+        from substack.post import Post
+
+        post = Post(
+            title=title,
+            subtitle=subtitle or "",
+            user_id=self.get_user_id(),
+            audience=audience,
+            write_comment_permissions=write_comment_permissions,
+        )
+        post.from_markdown(markdown, api=self)
+
+        draft = self.post_draft(post.get_draft())
+        draft_id = draft.get("id")
+
+        update_payload = {
+            "search_engine_title": search_engine_title,
+            "search_engine_description": search_engine_description,
+            "slug": slug,
+            "draft_section_id": draft_section_id,
+        }
+        update_payload = {
+            key: value for key, value in update_payload.items() if value is not None
+        }
+        if update_payload:
+            draft = self.put_draft(draft_id, **update_payload)
+
+        tags_result = None
+        tags_list = self._normalize_tags(tags)
+        if tags_list:
+            tags_result = self.add_tags_to_post(draft_id, tags_list)
+
+        prepublish_result = None
+        if prepublish:
+            prepublish_result = self.prepublish_draft(draft_id)
+
+        publish_result = None
+        if publish:
+            publish_result = self.publish_draft(
+                draft_id,
+                send=send,
+                share_automatically=share_automatically,
+            )
+
+        return {
+            "draft": draft,
+            "tags": tags_result,
+            "prepublish": prepublish_result,
+            "publish": publish_result,
+        }
+
+    def put_draft(self, draft, **kwargs) -> dict:
+        """
+
+        Args:
+            draft:
+            **kwargs:
+
+        Returns:
+
+        """
+        response = self._session.put(
+            f"{self.publication_url}/drafts/{draft}",
+            json=kwargs,
+        )
+        return Api._handle_response(response=response)
+
+    def prepublish_draft(self, draft) -> dict:
+        """
+
+        Args:
+            draft: draft id
+
+        Returns:
+
+        """
+
+        response = self._session.get(
+            f"{self.publication_url}/drafts/{draft}/prepublish"
+        )
+        return Api._handle_response(response=response)
+
+    def publish_draft(
+        self, draft, send: bool = True, share_automatically: bool = False
+    ) -> dict:
+        """
+
+        Args:
+            draft: draft id
+            send:
+            share_automatically:
+
+        Returns:
+
+        """
+        response = self._session.post(
+            f"{self.publication_url}/drafts/{draft}/publish",
+            json={"send": send, "share_automatically": share_automatically},
+        )
+        return Api._handle_response(response=response)
+
+    def schedule_draft(self, draft, draft_datetime: datetime) -> dict:
+        """
+
+        Args:
+            draft: draft id
+            draft_datetime: datetime to schedule the draft
+
+        Returns:
+
+        """
+        response = self._session.post(
+            f"{self.publication_url}/drafts/{draft}/scheduled_release",
+            json={"trigger_at": draft_datetime.isoformat()},
+        )
+        return Api._handle_response(response=response)
+
+    def unschedule_draft(self, draft) -> dict:
+        """
+
+        Args:
+            draft: draft id
+
+        Returns:
+
+        """
+        response = self._session.delete(
+            f"{self.publication_url}/drafts/{draft}/scheduled_release"
+        )
+        return Api._handle_response(response=response)
+
+    def get_image(self, image: str):
+        """
+
+        This method generates a new substack link that contains the image.
+
+        Args:
+            image: filepath or original url of image.
+
+        Returns:
+
+        """
+        if os.path.exists(image):
+            import mimetypes
+
+            mime_type, _ = mimetypes.guess_type(image)
+            if mime_type not in ["image/jpeg", "image/png", "image/gif", "image/webp"]:
+                ext = os.path.splitext(image)[1].lower()
+                if ext in [".jpg", ".jpeg"]:
+                    mime_type = "image/jpeg"
+                elif ext == ".png":
+                    mime_type = "image/png"
+                elif ext == ".gif":
+                    mime_type = "image/gif"
+                elif ext == ".webp":
+                    mime_type = "image/webp"
+                else:
+                    mime_type = "application/octet-stream"
+
+            with open(image, "rb") as file:
+                image_bytes = base64.b64encode(file.read())
+                image = f"data:{mime_type};base64,".encode("ascii") + image_bytes
+
+        response = self._session.post(
+            f"{self.publication_url}/image",
+            data={"image": image},
+        )
+        return Api._handle_response(response=response)
+
+    def add_tags_to_post(self, post_id: int, tag_names: list) -> dict:
+        """
+        Add multiple tags to a post.
+
+        Args:
+            post_id: The ID of the post to tag.
+            tag_names: A list of tag names to add.
+
+        Returns:
+            A dictionary with the results of applying all tags.
+        """
+        results = []
+        for tag_name in tag_names:
+            result = self.add_tag_to_post(post_id, tag_name)
+            results.append(result)
+        return {"tags_added": results}
+
+    def get_publication_post_tags(self) -> list:
+        """
+        Retrieve all post tags for the current publication.
+
+        Returns:
+            List of tag dicts as returned by Substack API.
+        """
+        response = self._session.get(f"{self.publication_url}/publication/post-tag")
+        return Api._handle_response(response=response)
+
+    def add_tag_to_post(self, post_id: int, tag_name: str) -> dict:
+        """
+        Add a tag to a post by first checking published tags and creating only if needed.
+
+        Args:
+            post_id: The ID of the post to tag.
+            tag_name: The name of the tag to add.
+
+        Returns:
+            The response from applying the tag to the post.
+        """
+        # Fetch existing publication tags first (avoid re-creating an already existing tag)
+        existing_tags = self.get_publication_post_tags() or []
+        existing_tag = next(
+            (tag for tag in existing_tags if tag.get("name") == tag_name),
+            None,
+        )
+
+        if existing_tag is not None:
+            tag_id = existing_tag["id"]
+        else:
+            create_tag_response = self._session.post(
+                f"{self.publication_url}/publication/post-tag",
+                json={"name": tag_name},
+            )
+            tag_data = Api._handle_response(create_tag_response)
+            tag_id = tag_data["id"]
+
+        apply_tag_response = self._session.post(
+            f"{self.publication_url}/post/{post_id}/tag/{tag_id}",
+        )
+        return Api._handle_response(apply_tag_response)
+
+    def get_categories(self):
+        """
+
+        Retrieve list of all available categories.
+
+        Returns:
+
+        """
+        response = self._session.get(f"{self.base_url}/categories")
+        return Api._handle_response(response=response)
+
+    def get_category(self, category_id, category_type, page):
+        """
+
+        Args:
+            category_id:
+            category_type:
+            page:
+
+        Returns:
+
+        """
+        response = self._session.get(
+            f"{self.base_url}/category/public/{category_id}/{category_type}",
+            params={"page": page},
+        )
+        return Api._handle_response(response=response)
+
+    def get_single_category(self, category_id, category_type, page=None, limit=None):
+        """
+
+        Args:
+            category_id:
+            category_type: paid or all
+            page: by default substack retrieves only the first 25 publications in the category. If this is left None,
+                  then all pages will be retrieved. The page size is 25 publications.
+            limit:
+        Returns:
+
+        """
+        if page is not None:
+            output = self.get_category(category_id, category_type, page)
+        else:
+            publications = []
+            page = 0
+            while True:
+                page_output = self.get_category(category_id, category_type, page)
+                publications.extend(page_output.get("publications", []))
+                if (
+                    limit is not None and limit <= len(publications)
+                ) or not page_output.get("more", False):
+                    publications = publications[:limit]
+                    break
+                page += 1
+            output = {
+                "publications": publications,
+                "more": page_output.get("more", False),
+            }
+        return output
+
+    def delete_all_drafts(self):
+        """
+
+        Returns:
+
+        """
+        response = None
+        while True:
+            drafts = self.get_drafts(filter="draft", limit=10, offset=0)
+            if len(drafts) == 0:
+                break
+            for draft in drafts:
+                response = self.delete_draft(draft.get("id"))
+        return response
+
+    def get_sections(self):
+        """
+        Get a list of the sections of your publication.
+
+        TODO: this is hacky but I cannot find another place where to get the sections.
+        Returns:
+
+        """
+        response = self._session.get(
+            f"{self.publication_url}/subscriptions",
+        )
+        content = Api._handle_response(response=response)
+        sections = [
+            p.get("sections")
+            for p in content.get("publications")
+            if p.get("hostname") in self.publication_url
+        ]
+        return sections[0]
+
+    def publication_embed(self, url):
+        """
+
+        Args:
+            url:
+
+        Returns:
+
+        """
+        return self.call("/publication/embed", "GET", url=url)
+
+    def call(self, endpoint, method, **params):
+        """
+
+        Args:
+            endpoint:
+            method:
+            **params:
+
+        Returns:
+
+        """
+        response = self._session.request(
+            method=method,
+            url=f"{self.publication_url}/{endpoint}",
+            params=params,
+        )
+        return Api._handle_response(response=response)