links-client 1.0.0__py3-none-any.whl

links_client/__init__.py

@@ -0,0 +1,22 @@
+"""
+Links Client - Python client library for link-cli (Links Theory database)
+
+This package provides a Python interface to the link-cli (clink) tool for
+working with Links Theory databases.
+"""
+
+from links_client.services.link_db_service import LinkDBService
+from links_client.services.menu_storage_service import MenuStorageService
+from links_client.services.auth_storage_service import AuthStorageService
+from links_client.api.ilinks import ILinks, LinkConstants
+from links_client.api.recursive_links import RecursiveLinks
+
+__version__ = "1.0.0"
+__all__ = [
+    "LinkDBService",
+    "MenuStorageService",
+    "AuthStorageService",
+    "ILinks",
+    "LinkConstants",
+    "RecursiveLinks"
+]

links_client/services/__init__.py

@@ -0,0 +1,7 @@
+"""Services for interacting with link-cli database"""
+
+from links_client.services.link_db_service import LinkDBService
+from links_client.services.menu_storage_service import MenuStorageService
+from links_client.services.auth_storage_service import AuthStorageService
+
+__all__ = ["LinkDBService", "MenuStorageService", "AuthStorageService"]

links_client/services/auth_storage_service.py

@@ -0,0 +1,561 @@
+"""AuthStorageService - Service for storing authentication data using link-cli"""
+
+import json
+import hashlib
+import time
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Optional, Any
+from links_client.services.link_db_service import LinkDBService
+from links_client.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Data directories for storing authentication data
+DATA_DIR = Path(__file__).parent.parent.parent.parent / "data" / "auth-data"
+USERS_DIR = DATA_DIR / "users"
+TOKENS_DIR = DATA_DIR / "tokens"
+PASSWORDS_DIR = DATA_DIR / "passwords"
+AUTH_DB_FILE = DATA_DIR / "auth.links"
+
+# Type identifiers for links
+USER_TYPE_ID = 2000  # Links of type (userId 2000) represent users
+TOKEN_LINK_PARENT = 3000  # Parent for token links (tokenId userId)
+PASSWORD_LINK_PARENT = 4000  # Parent for password links (passwordId userId)
+
+
+class AuthStorageService:
+    """
+    AuthStorageService - Store authentication data using link-cli
+
+    Architecture:
+    - Link-cli stores relationships between entities
+    - File system stores the actual data (JSON files)
+    - Links represent entity types and relationships
+
+    Link schemas:
+    1. Users: (userId 2000) - represents a user entity
+    2. Tokens: (tokenId userId) - token belongs to user
+    3. Passwords: (passwordId userId) - password belongs to user
+
+    File storage:
+    - data/auth-data/users/{userId}.json - user profile data
+    - data/auth-data/tokens/{tokenId}.json - token data
+    - data/auth-data/passwords/{passwordId}.json - hashed password data
+    """
+
+    def __init__(self):
+        """Initialize AuthStorageService"""
+        self.link_db = LinkDBService(str(AUTH_DB_FILE))
+        self._ensure_data_directories()
+
+    def _ensure_data_directories(self):
+        """Ensure all data directories exist"""
+        for directory in [DATA_DIR, USERS_DIR, TOKENS_DIR, PASSWORDS_DIR]:
+            directory.mkdir(parents=True, exist_ok=True)
+            logger.info(f"Ensured auth data directory exists: {directory}")
+
+    def generate_id(self, content: Dict[str, Any], prefix: str = '') -> str:
+        """
+        Generate a stable ID from content
+
+        Args:
+            content: Content object
+            prefix: ID prefix (e.g., 'user', 'token', 'pwd')
+
+        Returns:
+            Unique ID
+        """
+        content_str = json.dumps(content, sort_keys=True) + str(time.time())
+        hash_obj = hashlib.sha256(content_str.encode())
+        hash_hex = hash_obj.hexdigest()
+        numeric_id = int(hash_hex[:12], 16)
+        return f"{prefix}_{numeric_id}" if prefix else str(numeric_id)
+
+    def id_to_number(self, id_str: str) -> int:
+        """
+        Convert string ID to numeric for link storage
+
+        Args:
+            id_str: String ID
+
+        Returns:
+            Numeric ID
+        """
+        hash_obj = hashlib.sha256(id_str.encode())
+        hash_hex = hash_obj.hexdigest()
+        return int(hash_hex[:8], 16) % 1000000000
+
+    def save_data(self, directory: Path, item_id: str, data: Dict[str, Any]):
+        """
+        Save data to file
+
+        Args:
+            directory: Directory path
+            item_id: Item ID
+            data: Data to save
+        """
+        file_path = directory / f"{item_id}.json"
+        with open(file_path, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2)
+
+    def load_data(self, directory: Path, item_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Load data from file
+
+        Args:
+            directory: Directory path
+            item_id: Item ID
+
+        Returns:
+            Data or None if not found
+        """
+        file_path = directory / f"{item_id}.json"
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except FileNotFoundError:
+            return None
+
+    # ==================== USER OPERATIONS ====================
+
+    def create_user(self, user_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new user
+
+        Args:
+            user_data: User data (username, email, profile, etc.)
+
+        Returns:
+            Created user with ID
+        """
+        user_id = self.generate_id(user_data, 'user')
+        user_id_numeric = self.id_to_number(user_id)
+
+        # Save user data to file
+        user_data_with_id = {
+            **user_data,
+            'userId': user_id,
+            'createdAt': datetime.utcnow().isoformat()
+        }
+        self.save_data(USERS_DIR, user_id, user_data_with_id)
+
+        # Create link: (userId, USER_TYPE_ID)
+        try:
+            self.link_db.create_link(user_id_numeric, USER_TYPE_ID)
+            logger.info(f"User created in link database: {user_id}")
+        except Exception as error:
+            logger.error(f"Failed to create user link: {user_id}, error: {error}")
+            raise
+
+        return user_data_with_id
+
+    def get_user(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get user by ID
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            User data or None
+        """
+        return self.load_data(USERS_DIR, user_id)
+
+    def get_all_users(self) -> List[Dict[str, Any]]:
+        """
+        Get all users
+
+        Returns:
+            List of users
+        """
+        users = []
+        try:
+            for file_path in USERS_DIR.glob("*.json"):
+                user_data = self.load_data(USERS_DIR, file_path.stem)
+                if user_data:
+                    users.append(user_data)
+        except Exception as error:
+            logger.warning(f"Error reading users directory: {error}")
+
+        return users
+
+    def update_user(self, user_id: str, updates: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update user data
+
+        Args:
+            user_id: User ID
+            updates: Data to update
+
+        Returns:
+            Updated user data
+        """
+        existing_user = self.get_user(user_id)
+        if not existing_user:
+            raise ValueError(f"User {user_id} not found")
+
+        updated_user = {
+            **existing_user,
+            **updates,
+            'userId': user_id,  # Preserve userId
+            'updatedAt': datetime.utcnow().isoformat()
+        }
+
+        self.save_data(USERS_DIR, user_id, updated_user)
+        logger.info(f"User updated: {user_id}")
+
+        return updated_user
+
+    def delete_user(self, user_id: str) -> bool:
+        """
+        Delete user and all associated data (tokens, passwords)
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            Success status
+        """
+        user_id_numeric = self.id_to_number(user_id)
+
+        # Delete user's tokens
+        user_tokens = self.get_user_tokens(user_id)
+        for token in user_tokens:
+            self.delete_token(token['tokenId'])
+
+        # Delete user's passwords
+        user_passwords = self.get_user_passwords(user_id)
+        for pwd in user_passwords:
+            self.delete_password(pwd['passwordId'])
+
+        # Delete user link
+        all_links = self.link_db.read_all_links()
+        user_link = next(
+            (link for link in all_links
+             if link['source'] == user_id_numeric and link['target'] == USER_TYPE_ID),
+            None
+        )
+
+        if user_link:
+            self.link_db.delete_link(user_link['id'])
+
+        # Delete user data file
+        try:
+            file_path = USERS_DIR / f"{user_id}.json"
+            file_path.unlink()
+            logger.info(f"User deleted: {user_id}")
+        except Exception as error:
+            logger.warning(f"Failed to delete user data file: {user_id}, error: {error}")
+
+        return True
+
+    # ==================== TOKEN OPERATIONS ====================
+
+    def create_token(self, user_id: str, token_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new token for a user
+
+        Args:
+            user_id: User ID
+            token_data: Token data (apiKey, permissions, expiresAt, etc.)
+
+        Returns:
+            Created token with ID
+        """
+        token_id = self.generate_id(token_data, 'token')
+        token_id_numeric = self.id_to_number(token_id)
+        user_id_numeric = self.id_to_number(user_id)
+
+        # Save token data to file
+        token_data_with_id = {
+            **token_data,
+            'tokenId': token_id,
+            'userId': user_id,
+            'createdAt': datetime.utcnow().isoformat()
+        }
+        self.save_data(TOKENS_DIR, token_id, token_data_with_id)
+
+        # Create link: (tokenId, userId)
+        try:
+            self.link_db.create_link(token_id_numeric, user_id_numeric)
+            logger.info(f"Token created in link database: tokenId={token_id}, userId={user_id}")
+        except Exception as error:
+            logger.error(f"Failed to create token link: tokenId={token_id}, userId={user_id}, error: {error}")
+            raise
+
+        return token_data_with_id
+
+    def get_token(self, token_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get token by ID
+
+        Args:
+            token_id: Token ID
+
+        Returns:
+            Token data or None
+        """
+        return self.load_data(TOKENS_DIR, token_id)
+
+    def get_user_tokens(self, user_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all tokens for a user
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            List of tokens
+        """
+        tokens = []
+        try:
+            for file_path in TOKENS_DIR.glob("*.json"):
+                token_data = self.load_data(TOKENS_DIR, file_path.stem)
+                if token_data and token_data.get('userId') == user_id:
+                    tokens.append(token_data)
+        except Exception as error:
+            logger.warning(f"Error reading tokens directory: {error}")
+
+        return tokens
+
+    def delete_token(self, token_id: str) -> bool:
+        """
+        Delete a token
+
+        Args:
+            token_id: Token ID
+
+        Returns:
+            Success status
+        """
+        token_id_numeric = self.id_to_number(token_id)
+
+        # Delete token link
+        all_links = self.link_db.read_all_links()
+        token_link = next(
+            (link for link in all_links if link['source'] == token_id_numeric),
+            None
+        )
+
+        if token_link:
+            self.link_db.delete_link(token_link['id'])
+
+        # Delete token data file
+        try:
+            file_path = TOKENS_DIR / f"{token_id}.json"
+            file_path.unlink()
+            logger.info(f"Token deleted: {token_id}")
+        except Exception as error:
+            logger.warning(f"Failed to delete token data file: {token_id}, error: {error}")
+
+        return True
+
+    # ==================== PASSWORD OPERATIONS ====================
+
+    def set_password(self, user_id: str, password_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create/update password for a user
+
+        Args:
+            user_id: User ID
+            password_data: Password data (hash, salt, algorithm)
+
+        Returns:
+            Created/updated password with ID
+        """
+        # First, delete existing passwords for this user
+        existing_passwords = self.get_user_passwords(user_id)
+        for pwd in existing_passwords:
+            self.delete_password(pwd['passwordId'])
+
+        # Create new password
+        password_id = self.generate_id(password_data, 'pwd')
+        password_id_numeric = self.id_to_number(password_id)
+        user_id_numeric = self.id_to_number(user_id)
+
+        # Save password data to file
+        password_data_with_id = {
+            **password_data,
+            'passwordId': password_id,
+            'userId': user_id,
+            'createdAt': datetime.utcnow().isoformat()
+        }
+        self.save_data(PASSWORDS_DIR, password_id, password_data_with_id)
+
+        # Create link: (passwordId, userId)
+        try:
+            self.link_db.create_link(password_id_numeric, user_id_numeric)
+            logger.info(f"Password created in link database: passwordId={password_id}, userId={user_id}")
+        except Exception as error:
+            logger.error(f"Failed to create password link: passwordId={password_id}, userId={user_id}, error: {error}")
+            raise
+
+        return password_data_with_id
+
+    def get_user_password(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get password for a user
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            Password data or None
+        """
+        passwords = self.get_user_passwords(user_id)
+        # Return the most recent password (should only be one)
+        return passwords[0] if passwords else None
+
+    def get_user_passwords(self, user_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all passwords for a user (for migration/history)
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            List of passwords
+        """
+        passwords = []
+        try:
+            for file_path in PASSWORDS_DIR.glob("*.json"):
+                password_data = self.load_data(PASSWORDS_DIR, file_path.stem)
+                if password_data and password_data.get('userId') == user_id:
+                    passwords.append(password_data)
+        except Exception as error:
+            logger.warning(f"Error reading passwords directory: {error}")
+
+        return passwords
+
+    def delete_password(self, password_id: str) -> bool:
+        """
+        Delete a password
+
+        Args:
+            password_id: Password ID
+
+        Returns:
+            Success status
+        """
+        password_id_numeric = self.id_to_number(password_id)
+
+        # Delete password link
+        all_links = self.link_db.read_all_links()
+        password_link = next(
+            (link for link in all_links if link['source'] == password_id_numeric),
+            None
+        )
+
+        if password_link:
+            self.link_db.delete_link(password_link['id'])
+
+        # Delete password data file
+        try:
+            file_path = PASSWORDS_DIR / f"{password_id}.json"
+            file_path.unlink()
+            logger.info(f"Password deleted: {password_id}")
+        except Exception as error:
+            logger.warning(f"Failed to delete password data file: {password_id}, error: {error}")
+
+        return True
+
+    # ==================== STATISTICS & UTILITIES ====================
+
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get statistics about stored authentication data
+
+        Returns:
+            Statistics dictionary
+        """
+        all_links = self.link_db.read_all_links()
+
+        user_files = list(USERS_DIR.glob("*.json"))
+        token_files = list(TOKENS_DIR.glob("*.json"))
+        password_files = list(PASSWORDS_DIR.glob("*.json"))
+
+        return {
+            'totalLinks': len(all_links),
+            'users': {
+                'links': len([link for link in all_links if link['target'] == USER_TYPE_ID]),
+                'files': len(user_files)
+            },
+            'tokens': {
+                'links': len([link for link in all_links
+                            if link['target'] != USER_TYPE_ID and link['target'] < 1000000000]),
+                'files': len(token_files)
+            },
+            'passwords': {
+                'files': len(password_files)
+            }
+        }
+
+    def clear_all_auth_data(self) -> bool:
+        """
+        Clear all authentication data (DANGEROUS - use with caution)
+
+        Returns:
+            Success status
+        """
+        logger.warning("Clearing ALL authentication data - this is irreversible!")
+
+        # Clear link database
+        self.link_db.clear_database()
+
+        # Clear all data files
+        for directory in [USERS_DIR, TOKENS_DIR, PASSWORDS_DIR]:
+            try:
+                for file_path in directory.glob("*.json"):
+                    file_path.unlink()
+                logger.info(f"Cleared auth data directory: {directory}")
+            except Exception as error:
+                logger.warning(f"Failed to clear auth data directory: {directory}, error: {error}")
+
+        return True
+
+    def find_user_by_username(self, username: str) -> Optional[Dict[str, Any]]:
+        """
+        Find user by username (requires scanning all users)
+
+        Args:
+            username: Username to search for
+
+        Returns:
+            User data or None
+        """
+        all_users = self.get_all_users()
+        return next((user for user in all_users if user.get('username') == username), None)
+
+    def find_user_by_email(self, email: str) -> Optional[Dict[str, Any]]:
+        """
+        Find user by email (requires scanning all users)
+
+        Args:
+            email: Email to search for
+
+        Returns:
+            User data or None
+        """
+        all_users = self.get_all_users()
+        return next((user for user in all_users if user.get('email') == email), None)
+
+    def find_token_by_api_key(self, api_key: str) -> Optional[Dict[str, Any]]:
+        """
+        Find token by API key (requires scanning all tokens)
+
+        Args:
+            api_key: API key to search for
+
+        Returns:
+            Token data or None
+        """
+        try:
+            for file_path in TOKENS_DIR.glob("*.json"):
+                token_data = self.load_data(TOKENS_DIR, file_path.stem)
+                if token_data and token_data.get('apiKey') == api_key:
+                    return token_data
+        except Exception as error:
+            logger.warning(f"Error searching for token by API key: {error}")
+
+        return None

links_client/services/link_db_service.py

@@ -0,0 +1,286 @@
+"""LinkDBService - Service wrapper for link-cli (clink) database operations"""
+
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import List, Dict, Optional, Any
+from links_client.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Default database path
+DEFAULT_DB_DIR = Path(__file__).parent.parent.parent.parent / "data"
+DEFAULT_DB_FILE = DEFAULT_DB_DIR / "linkdb.links"
+
+
+class LinkDBService:
+    """
+    LinkDBService - Wrapper for link-cli database operations
+    Uses the clink tool (link-cli) for associative link-based data storage
+    """
+
+    def __init__(self, db_path: Optional[str] = None):
+        """
+        Initialize LinkDBService
+
+        Args:
+            db_path: Path to database file (defaults to DEFAULT_DB_FILE)
+        """
+        self.db_path = db_path or str(DEFAULT_DB_FILE)
+        self.next_id = 1  # Track next available ID for menu items
+
+    def execute_query(
+        self,
+        query: str,
+        before: bool = False,
+        changes: bool = False,
+        after: bool = False,
+        trace: bool = False
+    ) -> str:
+        """
+        Execute a clink command
+
+        Args:
+            query: LiNo query string
+            before: Show state before query
+            changes: Show changes
+            after: Show state after query
+            trace: Show trace information
+
+        Returns:
+            Command output
+
+        Raises:
+            RuntimeError: If clink is not available or query fails
+        """
+        flags = []
+        if before:
+            flags.append('--before')
+        if changes:
+            flags.append('--changes')
+        if after:
+            flags.append('--after')
+        if trace:
+            flags.append('--trace')
+
+        command = ['clink', query, '--db', self.db_path] + flags
+
+        try:
+            logger.debug(f"Executing clink command: {' '.join(command)}")
+
+            # Set PATH to include .dotnet/tools directory where clink is installed
+            env = os.environ.copy()
+            home = os.path.expanduser('~')
+            dotnet_tools = os.path.join(home, '.dotnet', 'tools')
+            env['PATH'] = f"{dotnet_tools}:{env.get('PATH', '')}"
+
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                env=env,
+                check=True
+            )
+
+            if result.stderr:
+                logger.warning(f"clink command produced stderr: {result.stderr}")
+
+            return result.stdout.strip()
+
+        except FileNotFoundError:
+            logger.error("clink command not found - link-cli may not be installed")
+            raise RuntimeError(
+                "LinkDB not available: clink command not found. "
+                "Please install link-cli."
+            )
+        except subprocess.CalledProcessError as error:
+            logger.error(f"Failed to execute clink command: {error}")
+            raise RuntimeError(f"LinkDB query failed: {error}")
+
+    def parse_links(self, output: str) -> List[Dict[str, int]]:
+        """
+        Parse clink output to extract links
+        Format: (id: source target)
+
+        Args:
+            output: Raw clink output
+
+        Returns:
+            List of parsed links
+        """
+        if not output or not output.strip():
+            return []
+
+        lines = [line.strip() for line in output.split('\n') if line.strip()]
+        links = []
+
+        for line in lines:
+            # Match pattern: (id: source target)
+            match = re.match(r'\((\d+):\s+(\d+)\s+(\d+)\)', line)
+            if match:
+                links.append({
+                    'id': int(match.group(1)),
+                    'source': int(match.group(2)),
+                    'target': int(match.group(3))
+                })
+
+        return links
+
+    def create_link(self, source: int, target: int) -> Dict[str, int]:
+        """
+        Create a new link
+
+        Args:
+            source: Source link ID
+            target: Target link ID
+
+        Returns:
+            Created link
+
+        Raises:
+            RuntimeError: If link creation fails
+        """
+        query = f"() (({source} {target}))"
+        output = self.execute_query(query, changes=True)
+
+        # Parse the created link from output
+        match = re.search(r'\((\d+):\s+(\d+)\s+(\d+)\)', output)
+        if match:
+            return {
+                'id': int(match.group(1)),
+                'source': int(match.group(2)),
+                'target': int(match.group(3))
+            }
+
+        raise RuntimeError("Failed to parse created link")
+
+    def read_all_links(self) -> List[Dict[str, int]]:
+        """
+        Read all links from database
+
+        Returns:
+            List of all links
+        """
+        query = "((($i: $s $t)) (($i: $s $t)))"
+        output = self.execute_query(query, after=True)
+        return self.parse_links(output)
+
+    def read_link(self, link_id: int) -> Optional[Dict[str, int]]:
+        """
+        Read a specific link by ID
+
+        Args:
+            link_id: Link ID
+
+        Returns:
+            Link or None if not found
+        """
+        query = f"((({link_id}: $s $t)) (({link_id}: $s $t)))"
+        output = self.execute_query(query, after=True)
+        links = self.parse_links(output)
+        return links[0] if links else None
+
+    def update_link(self, link_id: int, new_source: int, new_target: int) -> Dict[str, int]:
+        """
+        Update a link
+
+        Args:
+            link_id: Link ID
+            new_source: New source value
+            new_target: New target value
+
+        Returns:
+            Updated link
+        """
+        query = f"((({link_id}: $s $t)) (({link_id}: {new_source} {new_target})))"
+        self.execute_query(query, changes=True)
+
+        return {
+            'id': link_id,
+            'source': new_source,
+            'target': new_target
+        }
+
+    def delete_link(self, link_id: int) -> bool:
+        """
+        Delete a link
+
+        Args:
+            link_id: Link ID
+
+        Returns:
+            Success status
+        """
+        query = f"((({link_id}: $s $t)) ())"
+        self.execute_query(query, changes=True)
+        return True
+
+    def store_menu_item(self, menu_item: Dict[str, Any]) -> int:
+        """
+        Store menu item data as a link with encoded JSON
+        This is a higher-level abstraction for storing menu items
+
+        Args:
+            menu_item: Menu item object
+
+        Returns:
+            Link ID
+        """
+        # For now, we'll store the menu item as a link where:
+        # - source = incrementing ID
+        # - target = menu type identifier
+
+        menu_type_id = 1000  # Identifier for menu items
+        item_id = self.next_id
+        self.next_id += 1
+
+        link = self.create_link(item_id, menu_type_id)
+
+        # Store the actual JSON data separately (we'll need to implement a string storage mechanism)
+        # For now, return the link ID
+        return link['id']
+
+    def get_all_menu_items(self) -> List[Dict[str, int]]:
+        """
+        Get all menu items
+
+        Returns:
+            List of menu items
+        """
+        # Read all links with source pointing to menu type
+        all_links = self.read_all_links()
+
+        # Filter links that represent menu items (target = 1000)
+        menu_links = [link for link in all_links if link['target'] == 1000]
+
+        return menu_links
+
+    def delete_menu_item(self, link_id: int) -> bool:
+        """
+        Delete menu item
+
+        Args:
+            link_id: Link ID
+
+        Returns:
+            Success status
+        """
+        return self.delete_link(link_id)
+
+    def clear_database(self) -> bool:
+        """
+        Clear all data from database
+
+        Returns:
+            Success status
+        """
+        try:
+            # Delete all links one by one
+            all_links = self.read_all_links()
+            for link in all_links:
+                self.delete_link(link['id'])
+            return True
+        except Exception as error:
+            logger.error(f"Failed to clear database: {error}")
+            raise

links_client/services/menu_storage_service.py

@@ -0,0 +1,271 @@
+"""MenuStorageService - Service for storing menu configuration using link-cli"""
+
+import json
+import hashlib
+from pathlib import Path
+from typing import List, Dict, Optional, Any
+from links_client.services.link_db_service import LinkDBService
+from links_client.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Data directory for storing menu item content
+DATA_DIR = Path(__file__).parent.parent.parent.parent / "data" / "menu-items"
+
+
+class MenuStorageService:
+    """
+    MenuStorageService - Store menu configurations using link-cli
+
+    Architecture:
+    - Link-cli stores the relationships and structure (menu hierarchy)
+    - File system stores the actual menu item data (JSON files)
+    - Links represent parent-child relationships in menu structure
+
+    Link schema:
+    - Link (menuItemId, parentId) represents a menu item under a parent
+    - Special parentId = 0 means root-level menu item
+    - Link IDs are derived from content hashes for consistency
+    """
+
+    def __init__(self):
+        """Initialize MenuStorageService"""
+        self.link_db = LinkDBService()
+        self._ensure_data_directory()
+
+    def _ensure_data_directory(self):
+        """Ensure data directory exists"""
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        logger.info(f"Ensured menu items data directory exists: {DATA_DIR}")
+
+    def generate_item_id(self, item: Dict[str, Any]) -> int:
+        """
+        Generate a stable ID from menu item content
+
+        Args:
+            item: Menu item
+
+        Returns:
+            Numeric ID
+        """
+        content = json.dumps(item, sort_keys=True)
+        hash_obj = hashlib.sha256(content.encode())
+        hash_hex = hash_obj.hexdigest()
+        # Take first 8 characters of hash and convert to number
+        return int(hash_hex[:8], 16) % 1000000  # Keep it reasonable
+
+    def save_item_data(self, item_id: int, item: Dict[str, Any]):
+        """
+        Save menu item data to file
+
+        Args:
+            item_id: Item ID
+            item: Menu item data
+        """
+        file_path = DATA_DIR / f"{item_id}.json"
+        with open(file_path, 'w', encoding='utf-8') as f:
+            json.dump(item, f, indent=2)
+
+    def load_item_data(self, item_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Load menu item data from file
+
+        Args:
+            item_id: Item ID
+
+        Returns:
+            Menu item or None if not found
+        """
+        file_path = DATA_DIR / f"{item_id}.json"
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except FileNotFoundError:
+            return None
+
+    def store_menu_item(self, item: Dict[str, Any], parent_id: int = 0) -> int:
+        """
+        Store a menu item with its parent relationship
+
+        Args:
+            item: Menu item (must have label, icon, to/items)
+            parent_id: Parent item ID (0 for root)
+
+        Returns:
+            Item ID
+        """
+        item_id = self.generate_item_id(item)
+
+        # Save item data to file
+        self.save_item_data(item_id, item)
+
+        # Create link in database: (itemId, parentId)
+        try:
+            self.link_db.create_link(item_id, parent_id)
+            logger.info(f"Menu item stored in link database: itemId={item_id}, parentId={parent_id}")
+        except Exception as error:
+            # Link might already exist, that's okay
+            logger.debug(f"Link already exists or failed to create: itemId={item_id}, parentId={parent_id}")
+
+        return item_id
+
+    def store_menu_structure(self, menu_items: List[Dict[str, Any]], parent_id: int = 0) -> List[int]:
+        """
+        Store a complete menu structure recursively
+
+        Args:
+            menu_items: Menu items array
+            parent_id: Parent ID
+
+        Returns:
+            List of created item IDs
+        """
+        item_ids = []
+
+        for item in menu_items:
+            # Create a copy without nested items for the link
+            item_without_children = {k: v for k, v in item.items() if k != 'items'}
+            children = item.get('items', [])
+
+            # Store the item
+            item_id = self.store_menu_item(item_without_children, parent_id)
+            item_ids.append(item_id)
+
+            # Recursively store children
+            if children and isinstance(children, list) and len(children) > 0:
+                self.store_menu_structure(children, item_id)
+
+        return item_ids
+
+    def get_menu_structure(self, parent_id: int = 0) -> List[Dict[str, Any]]:
+        """
+        Retrieve menu structure by building from links
+
+        Args:
+            parent_id: Parent ID (0 for root)
+
+        Returns:
+            List of menu items
+        """
+        # Get all links from database
+        all_links = self.link_db.read_all_links()
+
+        # Filter links that have this parent
+        child_links = [link for link in all_links if link['target'] == parent_id]
+
+        # Build menu items
+        menu_items = []
+
+        for link in child_links:
+            item_id = link['source']
+
+            # Load item data
+            item_data = self.load_item_data(item_id)
+
+            if item_data:
+                # Recursively get children
+                children = self.get_menu_structure(item_id)
+
+                menu_item = {
+                    **item_data,
+                    '_linkId': link['id'],
+                    '_itemId': item_id
+                }
+
+                # Add children if any
+                if children:
+                    menu_item['items'] = children
+
+                menu_items.append(menu_item)
+
+        return menu_items
+
+    def get_all_menu_items(self) -> List[Dict[str, Any]]:
+        """
+        Get all menu items (flat list)
+
+        Returns:
+            List of all menu items
+        """
+        all_links = self.link_db.read_all_links()
+        items = []
+
+        for link in all_links:
+            item_data = self.load_item_data(link['source'])
+            if item_data:
+                items.append({
+                    **item_data,
+                    '_linkId': link['id'],
+                    '_itemId': link['source'],
+                    '_parentId': link['target']
+                })
+
+        return items
+
+    def delete_menu_item(self, item_id: int) -> bool:
+        """
+        Delete a menu item and its children
+
+        Args:
+            item_id: Item ID
+
+        Returns:
+            Success status
+        """
+        # Get all child items
+        children = self.get_menu_structure(item_id)
+
+        # Recursively delete children
+        for child in children:
+            self.delete_menu_item(child['_itemId'])
+
+        # Delete links where this item is the source
+        all_links = self.link_db.read_all_links()
+        item_links = [link for link in all_links if link['source'] == item_id]
+
+        for link in item_links:
+            self.link_db.delete_link(link['id'])
+
+        # Delete item data file
+        try:
+            file_path = DATA_DIR / f"{item_id}.json"
+            file_path.unlink()
+        except Exception as error:
+            logger.warning(f"Failed to delete item data file: itemId={item_id}, error={error}")
+
+        return True
+
+    def clear_all_menus(self) -> bool:
+        """
+        Clear all menu data
+
+        Returns:
+            Success status
+        """
+        # Clear link database
+        self.link_db.clear_database()
+
+        # Clear all menu item files
+        try:
+            for file_path in DATA_DIR.glob("*.json"):
+                file_path.unlink()
+        except Exception as error:
+            logger.warning(f"Failed to clear menu data files: {error}")
+
+        return True
+
+    def get_statistics(self) -> Dict[str, int]:
+        """
+        Get statistics about stored menu data
+
+        Returns:
+            Statistics dictionary
+        """
+        all_links = self.link_db.read_all_links()
+        json_files = list(DATA_DIR.glob("*.json"))
+
+        return {
+            'totalLinks': len(all_links),
+            'totalFiles': len(json_files),
+            'rootItems': len([link for link in all_links if link['target'] == 0])
+        }

links_client/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules"""
+
+from links_client.utils.logger import get_logger
+
+__all__ = ["get_logger"]

links_client/utils/logger.py

@@ -0,0 +1,41 @@
+"""Logging utility for links-client"""
+
+import logging
+import sys
+from typing import Optional
+
+
+def get_logger(name: str = "links_client", level: Optional[int] = None) -> logging.Logger:
+    """
+    Get or create a logger instance
+
+    Args:
+        name: Logger name
+        level: Logging level (defaults to WARNING)
+
+    Returns:
+        Logger instance
+    """
+    logger = logging.getLogger(name)
+
+    # Only configure if not already configured
+    if not logger.handlers:
+        if level is None:
+            level = logging.WARNING
+
+        logger.setLevel(level)
+
+        # Create console handler
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(level)
+
+        # Create formatter
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        handler.setFormatter(formatter)
+
+        logger.addHandler(handler)
+
+    return logger

links_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: links-client
+Version: 1.0.0
+Summary: Python client library for link-cli (Links Theory database)
+Author: DronDoc Team
+License: Unlicense
+Project-URL: Homepage, https://github.com/link-foundation/links-client
+Project-URL: Repository, https://github.com/link-foundation/links-client
+Project-URL: Issues, https://github.com/link-foundation/links-client/issues
+Keywords: link-cli,links-theory,database,associative,clink
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Public Domain
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+
+# Links Client - Python Implementation
+
+Python client library for [link-cli](https://github.com/link-foundation/link-cli) — implementation of Links Theory database.
+
+## Installation
+
+### Prerequisites
+
+Install link-cli globally:
+```bash
+dotnet tool install --global clink
+```
+
+### Package Installation
+
+```bash
+pip install -e .
+```
+
+Or install from the repository root:
+
+```bash
+cd python
+pip install -e .
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from links_client import LinkDBService
+
+db = LinkDBService('/path/to/database.links')
+
+# Create a link
+link = db.create_link(100, 200)
+print(link)  # {'id': 1, 'source': 100, 'target': 200}
+
+# Read all links
+links = db.read_all_links()
+
+# Delete a link
+db.delete_link(1)
+```
+
+### Menu Storage
+
+```python
+from links_client import MenuStorageService
+
+menu_storage = MenuStorageService()
+
+menu = [
+    {
+        "label": "Dashboard",
+        "icon": "pi pi-home",
+        "to": "/dashboard",
+        "items": [
+            {"label": "Analytics", "to": "/dashboard/analytics"}
+        ]
+    }
+]
+
+menu_storage.store_menu_structure(menu, 0)
+retrieved_menu = menu_storage.get_menu_structure(0)
+```
+
+### Authentication Storage
+
+```python
+from links_client import AuthStorageService
+
+auth_storage = AuthStorageService()
+
+# Create user
+user = auth_storage.create_user({
+    "username": "alice",
+    "email": "alice@example.com"
+})
+
+# Set password
+auth_storage.set_password(user['userId'], {
+    "hash": "hashed_password",
+    "salt": "random_salt"
+})
+```
+
+## API
+
+For detailed API documentation, see the docs/ directory.
+
+## Examples
+
+See examples in the examples/ directory:
+
+- `basic_usage.py` - Basic clink integration tests
+- `menu_storage_example.py` - Menu storage demonstration
+- `auth_storage_example.py` - Authentication storage demonstration
+
+## Testing
+
+Run tests with pytest:
+
+```bash
+pytest tests/
+```
+
+## License
+
+The Unlicense
+
+## Links
+
+- Source repository: https://github.com/link-foundation/links-client
+- link-cli: https://github.com/link-foundation/link-cli

links_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+links_client/__init__.py,sha256=P9NUBwfms4dnNbrlQLSe9H1hDnJqLJU_XqcF20ID8xc,691
+links_client/services/__init__.py,sha256=Obq56i8AjqtMcbFRJdjvRiPZBWmQjtmwIXl5uKU2-wo,340
+links_client/services/auth_storage_service.py,sha256=zpRSI9hNubY1Ra8ECH8bR8uNKj-aKUmRV_w2YFZiqEs,17538
+links_client/services/link_db_service.py,sha256=aqqSlLscZ96BVXgNXICR9CGByY4s39I-OciAwCZbhmY,8108
+links_client/services/menu_storage_service.py,sha256=JnGvYL5tEVJhtPHC9aFLHTaIhiVRMtFSdd9Jf_Mzhn0,8150
+links_client/utils/__init__.py,sha256=hAGOfxhB2d-8GFk6Gn4-lTGDDk26DzyhwEMx0_dO5-I,98
+links_client/utils/logger.py,sha256=W_fa5Z4Y5RiUUOFlZFBn79mN_KWB967k67KwfqyF-lI,970
+links_client-1.0.0.dist-info/METADATA,sha256=uQ4-x9oK0LVttIdHpU37q8PjD3ENhLv_5378sTHL3bY,3069
+links_client-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+links_client-1.0.0.dist-info/top_level.txt,sha256=DBKi60S1rGFP8QU5lgEzUIEpz_G4gq0AVfJlNC_0V7U,13
+links_client-1.0.0.dist-info/RECORD,,

links_client-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

links_client-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+links_client