docspan 0.1.0__py3-none-any.whl

docspan/backends/confluence/services/confluence/space_client.py

@@ -0,0 +1,179 @@
+"""
+Client for managing Confluence spaces.
+
+This module provides specialized functionality for working with Confluence spaces,
+including retrieving space information and content.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from docspan.backends.confluence.config.models import ConfluenceConfig
+from docspan.backends.confluence.services.confluence.base_client import BaseConfluenceClient
+
+
+class SpaceClient(BaseConfluenceClient):
+    """
+    Client for managing Confluence spaces.
+    
+    Provides methods for retrieving space information and content.
+    """
+    
+    def __init__(self, config: ConfluenceConfig):
+        """
+        Initialize the space client.
+        
+        Args:
+            config: Confluence configuration
+        """
+        super().__init__(config)
+    
+    def get_space(self, space_key: str) -> Dict[str, Any]:
+        """
+        Get information about a space.
+        
+        Args:
+            space_key: Space key
+            
+        Returns:
+            Space data
+        """
+        endpoint = f"space/{space_key}"
+        params = {"expand": "description,homepage"}
+        
+        return self._make_request(
+            method="GET",
+            endpoint=endpoint,
+            params=params
+        )
+    
+    def get_spaces(
+        self, 
+        start: int = 0, 
+        limit: int = 25,
+        type: Optional[str] = None,
+        status: Optional[str] = None,
+        expand: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Get all spaces or filtered spaces.
+        
+        Args:
+            start: Start index for pagination
+            limit: Maximum number of results to return
+            type: Space type filter (global, personal)
+            status: Space status filter (current, archived)
+            expand: Additional properties to expand in the response
+            
+        Returns:
+            List of space data
+        """
+        endpoint = "space"
+        params = {
+            "start": start,
+            "limit": limit
+        }
+        
+        if type:
+            params["type"] = type
+        
+        if status:
+            params["status"] = status
+            
+        if expand:
+            params["expand"] = expand
+        
+        response = self._make_request(
+            method="GET",
+            endpoint=endpoint,
+            params=params
+        )
+        
+        # Return the results
+        if isinstance(response, dict):
+            return response.get("results", [])
+        
+        return []
+    
+    def get_space_content(
+        self,
+        space_key: str,
+        content_type: str = "page",
+        start: int = 0,
+        limit: int = 25,
+        expand: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Get content in a space.
+        
+        Args:
+            space_key: Space key
+            content_type: Content type (page, blogpost, comment)
+            start: Start index for pagination
+            limit: Maximum number of results to return
+            expand: Additional properties to expand in the response
+            
+        Returns:
+            List of content data
+        """
+        endpoint = f"space/{space_key}/content/{content_type}"
+        params = {
+            "start": start,
+            "limit": limit
+        }
+        
+        if expand:
+            params["expand"] = expand
+        
+        response = self._make_request(
+            method="GET",
+            endpoint=endpoint,
+            params=params
+        )
+        
+        # Return the results
+        if isinstance(response, dict):
+            return response.get("results", [])
+        
+        return []
+    
+    def search_space_content(
+        self,
+        space_key: str,
+        query: str,
+        start: int = 0,
+        limit: int = 25
+    ) -> List[Dict[str, Any]]:
+        """
+        Search for content in a space.
+        
+        Args:
+            space_key: Space key
+            query: Search query
+            start: Start index for pagination
+            limit: Maximum number of results to return
+            
+        Returns:
+            List of content data matching the search query
+        """
+        # Use CQL (Confluence Query Language)
+        cql = f"space = {space_key} AND text ~ \"{query}\""
+        
+        endpoint = "content/search"
+        params = {
+            "cql": cql,
+            "start": start,
+            "limit": limit,
+            "expand": "space,version"
+        }
+        
+        response = self._make_request(
+            method="GET",
+            endpoint=endpoint,
+            params=params
+        )
+        
+        # Return the results
+        if isinstance(response, dict):
+            return response.get("results", [])
+        
+        return []

docspan/backends/confluence/services/confluence/url_parser.py

@@ -0,0 +1,106 @@
+"""
+Utilities for parsing Confluence URLs.
+
+This module provides functions to extract page IDs and space keys from Confluence URLs.
+"""
+
+import re
+from typing import Optional, Tuple
+
+
+class ConfluenceUrlParser:
+    """Parser for Confluence URLs."""
+
+    # Pattern for Confluence page URLs:
+    # https://{domain}/wiki/spaces/{space_key}/pages/{page_id}/{title}
+    PAGE_URL_PATTERN = re.compile(
+        r'/wiki/spaces/(?P<space_key>[^/]+)/pages/(?P<page_id>\d+)(?:/|$)'
+    )
+
+    @classmethod
+    def parse_page_url(cls, url: str) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Parse a Confluence page URL to extract page ID and space key.
+
+        Args:
+            url: Confluence page URL
+
+        Returns:
+            Tuple of (page_id, space_key), or (None, None) if parsing fails
+
+        Examples:
+            >>> parser = ConfluenceUrlParser()
+            >>> parser.parse_page_url('https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456/Page+Title')
+            ('123456', 'MYSPACE')
+            >>> parser.parse_page_url('https://example.atlassian.net/wiki/spaces/~630044b443e43992b9a3e6f2/pages/973308410/Reliability+Manifesto')
+            ('973308410', '~630044b443e43992b9a3e6f2')
+        """
+        match = cls.PAGE_URL_PATTERN.search(url)
+        if match:
+            return match.group('page_id'), match.group('space_key')
+        return None, None
+
+    @classmethod
+    def extract_page_id(cls, url_or_id: str) -> Optional[str]:
+        """
+        Extract page ID from a URL or return the ID if already provided.
+
+        Args:
+            url_or_id: Either a Confluence URL or a page ID
+
+        Returns:
+            Page ID or None if not found
+
+        Examples:
+            >>> parser = ConfluenceUrlParser()
+            >>> parser.extract_page_id('123456')
+            '123456'
+            >>> parser.extract_page_id('https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456/Title')
+            '123456'
+        """
+        # If it's already just a number, return it
+        if url_or_id.isdigit():
+            return url_or_id
+
+        # Try to parse as URL
+        page_id, _ = cls.parse_page_url(url_or_id)
+        return page_id
+
+    @classmethod
+    def extract_space_key(cls, url: str) -> Optional[str]:
+        """
+        Extract space key from a Confluence URL.
+
+        Args:
+            url: Confluence page URL
+
+        Returns:
+            Space key or None if not found
+
+        Examples:
+            >>> parser = ConfluenceUrlParser()
+            >>> parser.extract_space_key('https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456/Title')
+            'MYSPACE'
+        """
+        _, space_key = cls.parse_page_url(url)
+        return space_key
+
+    @classmethod
+    def is_confluence_url(cls, text: str) -> bool:
+        """
+        Check if the text looks like a Confluence URL.
+
+        Args:
+            text: Text to check
+
+        Returns:
+            True if it looks like a Confluence URL
+
+        Examples:
+            >>> parser = ConfluenceUrlParser()
+            >>> parser.is_confluence_url('https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456')
+            True
+            >>> parser.is_confluence_url('123456')
+            False
+        """
+        return cls.PAGE_URL_PATTERN.search(text) is not None

docspan/backends/google_docs/auth.py

@@ -0,0 +1,143 @@
+"""
+Google Drive Authentication Module
+
+Handles authentication for two separate Google accounts:
+- Account A: Google Docs source
+- Account B: Obsidian vault storage
+"""
+
+import json
+import logging
+import os
+
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+
+logger = logging.getLogger(__name__)
+
+# Google Drive API scopes
+PULL_SCOPES = [
+    "https://www.googleapis.com/auth/documents.readonly",
+    "https://www.googleapis.com/auth/drive.readonly",
+    "https://www.googleapis.com/auth/spreadsheets.readonly",
+]
+
+PUSH_SCOPES = [
+    "https://www.googleapis.com/auth/documents",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/spreadsheets.readonly",
+]
+
+# Default to read-write scopes so push works out of the box.
+# Note: existing tokens created with documents.readonly are insufficient for push.
+DEFAULT_SCOPES = PUSH_SCOPES
+
+# Legacy alias — kept so any code that references SCOPES still works.
+SCOPES = DEFAULT_SCOPES
+
+
+class GoogleAuthenticator:
+    """Handles Google API authentication"""
+
+    def __init__(self, credentials_json=None, credentials_path=None):
+        """
+        Initialize authenticator with service account credentials
+
+        Args:
+            credentials_json: JSON string of service account credentials
+            credentials_path: Path to service account JSON file
+        """
+        self.credentials = None
+
+        if credentials_json:
+            # Load from JSON string (for Railway env vars)
+            creds_dict = json.loads(credentials_json)
+            self.credentials = service_account.Credentials.from_service_account_info(
+                creds_dict, scopes=SCOPES
+            )
+            logger.info("Loaded credentials from JSON string")
+        elif credentials_path:
+            # Load from file (for local development)
+            self.credentials = service_account.Credentials.from_service_account_file(
+                credentials_path, scopes=SCOPES
+            )
+            logger.info(f"Loaded credentials from file: {credentials_path}")
+        else:
+            raise ValueError("Either credentials_json or credentials_path must be provided")
+
+    def get_credentials(self):
+        """
+        Get valid credentials
+
+        Returns:
+            google.auth.credentials.Credentials
+        """
+        if not self.credentials:
+            raise ValueError("Credentials not initialized")
+
+        # Refresh if needed
+        if not self.credentials.valid:
+            logger.info("Refreshing credentials")
+            self.credentials.refresh(Request())
+
+        return self.credentials
+
+
+class DualAccountAuth:
+    """Manages authentication for both Google accounts"""
+
+    def __init__(self):
+        """Initialize dual account authentication from environment variables"""
+        self.account_a_auth = None
+        self.account_b_auth = None
+        self._load_from_env()
+
+    def _load_from_env(self):
+        """Load credentials from environment variables"""
+        # Account A (Google Docs)
+        account_a_json = os.getenv('ACCOUNT_A_CREDENTIALS')
+        account_a_path = os.getenv('ACCOUNT_A_CREDENTIALS_PATH')
+
+        if account_a_json:
+            self.account_a_auth = GoogleAuthenticator(credentials_json=account_a_json)
+        elif account_a_path:
+            self.account_a_auth = GoogleAuthenticator(credentials_path=account_a_path)
+        else:
+            logger.warning("Account A credentials not found in environment")
+
+        # Account B (Obsidian Vault)
+        account_b_json = os.getenv('ACCOUNT_B_CREDENTIALS')
+        account_b_path = os.getenv('ACCOUNT_B_CREDENTIALS_PATH')
+
+        if account_b_json:
+            self.account_b_auth = GoogleAuthenticator(credentials_json=account_b_json)
+        elif account_b_path:
+            self.account_b_auth = GoogleAuthenticator(credentials_path=account_b_path)
+        else:
+            logger.warning("Account B credentials not found in environment")
+
+    def get_account_a_credentials(self):
+        """
+        Get credentials for Account A (Google Docs)
+
+        Returns:
+            google.auth.credentials.Credentials
+        """
+        if not self.account_a_auth:
+            raise ValueError("Account A not authenticated. Check ACCOUNT_A_CREDENTIALS env var")
+        return self.account_a_auth.get_credentials()
+
+    def get_account_b_credentials(self):
+        """
+        Get credentials for Account B (Obsidian Vault)
+
+        Returns:
+            google.auth.credentials.Credentials
+        """
+        if not self.account_b_auth:
+            raise ValueError("Account B not authenticated. Check ACCOUNT_B_CREDENTIALS env var")
+        return self.account_b_auth.get_credentials()
+
+    def is_authenticated(self) -> bool:
+        """Return True if the primary Google Docs account (account A) is configured."""
+        return self.account_a_auth is not None

docspan/backends/google_docs/backend.py

@@ -0,0 +1,140 @@
+"""Google Docs backend."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+from typing import TYPE_CHECKING
+
+from docspan.backends.base import Backend, PullResult, PushResult
+from docspan.backends.google_docs.auth import DualAccountAuth, GoogleAuthenticator
+from docspan.backends.google_docs.client import GoogleDocsClient
+from docspan.backends.google_docs.converter import DocumentConverter
+from docspan.backends.google_docs.docs_request_builder import DocsRequestBuilder
+from docspan.backends.google_docs.docs_structure_parser import DocsStructureParser
+from docspan.backends.google_docs.markdown_to_paragraph_parser import MarkdownToParagraphParser
+
+if TYPE_CHECKING:
+    from docspan.config import GoogleDocsConfig, MarkgateConfig
+
+
+class GoogleDocsBackend(Backend):
+    name = "google_docs"
+
+    def __init__(self, config: "GoogleDocsConfig") -> None:
+        self.config = config
+        self._client: GoogleDocsClient | None = None
+
+    @classmethod
+    def from_config(cls, markgate_config: "MarkgateConfig") -> "GoogleDocsBackend":
+        from docspan.config import GoogleDocsConfig
+        return cls(markgate_config.backends.google_docs or GoogleDocsConfig())
+
+    def _ensure_client(self) -> None:
+        if self._client is not None:
+            return
+        if self.config.credentials_path:
+            auth = GoogleAuthenticator(credentials_path=self.config.credentials_path)
+            self._client = GoogleDocsClient(auth.get_credentials())
+        else:
+            dual = DualAccountAuth()
+            if not dual.is_authenticated():
+                raise RuntimeError(
+                    "Google Docs credentials not found. "
+                    "Set credentials_path in markgate.yaml or ACCOUNT_A_CREDENTIALS_PATH env var. "
+                    "Run: docspan auth setup google_docs"
+                )
+            self._client = GoogleDocsClient(dual.get_account_a_credentials())
+
+    def push(self, local_path: str, doc_id: str, **kwargs: object) -> PushResult:
+        """Convert local markdown to Google Docs format using structural diff and batch update."""
+        self._ensure_client()
+        assert self._client is not None
+        try:
+            content = pathlib.Path(local_path).read_text()
+
+            target_nodes = MarkdownToParagraphParser().parse(content)
+            doc = self._client.get_document(doc_id)
+            current_nodes = DocsStructureParser().parse(doc)
+
+            if "tabs" in doc and doc["tabs"]:
+                body_content = doc["tabs"][0].get("documentTab", doc).get("body", {}).get("content", [])
+            else:
+                body_content = doc.get("body", {}).get("content", [])
+            doc_end_index = body_content[-1].get("endIndex", 1) if body_content else 1
+
+            requests = DocsRequestBuilder().build(current_nodes, target_nodes, doc_end_index)
+            if not requests:
+                return PushResult(status="skipped", doc_id=doc_id, message="No changes detected")
+
+            self._client.batch_update(doc_id, requests)
+            url = f"https://docs.google.com/document/d/{doc_id}/edit"
+            return PushResult(status="ok", doc_id=doc_id, url=url)
+        except Exception as exc:
+            return PushResult(status="error", doc_id=doc_id, message=str(exc))
+
+    def pull(self, doc_id: str, local_path: str, **kwargs: object) -> PullResult:
+        """Export Google Doc as HTML, convert to markdown, write locally."""
+        self._ensure_client()
+        assert self._client is not None
+        try:
+            html_content = self._client.get_doc_content(doc_id)
+            markdown_content = DocumentConverter().html_to_markdown(html_content)
+            pathlib.Path(local_path).parent.mkdir(parents=True, exist_ok=True)
+            pathlib.Path(local_path).write_text(markdown_content)
+            return PullResult(status="ok", doc_id=doc_id, local_path=local_path)
+        except Exception as exc:
+            return PullResult(status="error", doc_id=doc_id, local_path=local_path, message=str(exc))
+
+    def get_remote_version(self, doc_id: str) -> str:
+        """Return the revisionId of the Google Doc (opaque, non-empty string)."""
+        self._ensure_client()
+        assert self._client is not None
+        doc = self._client.get_document(doc_id)
+        return doc["revisionId"]
+
+    def auth_setup(self) -> None:
+        """Print setup instructions for Google Docs service account credentials."""
+        has_path = self.config.credentials_path or os.getenv("ACCOUNT_A_CREDENTIALS_PATH")
+        has_json = os.getenv("ACCOUNT_A_CREDENTIALS")
+
+        if has_path or has_json:
+            print("Google Docs credentials are already configured.")
+            try:
+                self._ensure_client()
+                print("✓ Connection verified successfully.")
+            except Exception as exc:
+                print(f"✗ Connection test failed: {exc}")
+            return
+
+        print("\nGoogle Docs Auth Setup")
+        print("=" * 40)
+        print("docspan uses Google service account credentials for Google Docs access.")
+        print("\nSetup steps:")
+        print("  1. Create a service account at:")
+        print("     https://console.cloud.google.com/iam-admin/serviceaccounts")
+        print("  2. Enable Google Docs API and Google Drive API in your project")
+        print("  3. Download the service account JSON key file")
+        print("  4. Share your Google Docs with the service account email")
+        print("\nConfigure credentials via one of:")
+        print("  Option A — YAML config:")
+        print("    backends:")
+        print("      google_docs:")
+        print("        credentials_path: /path/to/service-account.json")
+        print("  Option B — environment variable (path):")
+        print("    export ACCOUNT_A_CREDENTIALS_PATH=/path/to/service-account.json")
+        print("  Option C — environment variable (inline JSON):")
+        print("    export ACCOUNT_A_CREDENTIALS='{ ... service account JSON ... }'")
+
+    def validate_config(self) -> None:
+        has_credentials = (
+            self.config.credentials_path
+            or os.getenv("ACCOUNT_A_CREDENTIALS_PATH")
+            or os.getenv("ACCOUNT_A_CREDENTIALS")
+        )
+        if not has_credentials:
+            raise ValueError(
+                "Missing Google Docs credentials. "
+                "Set credentials_path in markgate.yaml or ACCOUNT_A_CREDENTIALS_PATH env var. "
+                "Run: docspan auth setup google_docs"
+            )