clappia-api-tools 0.1.5__py3-none-any.whl

clappia_api_tools-0.1.5.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: clappia-api-tools
+Version: 0.1.5
+Summary: Python client for Clappia API integration
+Author-email: Rishabh Verma <rishabh.v@clappia.com>
+License: MIT
+Project-URL: Homepage, https://github.com/clappia-dev/clappia-tools
+Project-URL: Documentation, https://github.com/clappia-dev/clappia-tools#readme
+Project-URL: Repository, https://github.com/clappia-dev/clappia-tools.git
+Project-URL: Bug Tracker, https://github.com/clappia-dev/clappia-tools/issues
+Keywords: clappia,client,mcp,rest-apis,tools,workchat,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.4.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Dynamic: license-file
+
+# Clappia Tools
+
+**LangChain integration for Clappia API**
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/clappia-tools)](https://pypi.org/project/clappia-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Overview
+
+Clappia Tools is a Python package that provides a unified client and a set of tools for seamless integration with the [Clappia API](https://www.clappia.com/). It enables developers to automate workflows, manage submissions, and interact with Clappia apps programmatically. The package is designed for use in automation, data integration, and agent-based systems (e.g., LangChain agents).
+
+---
+
+## Features
+
+-  **Unified API Client**: One client for all Clappia API operations.
+-  **Submission Management**: Create, edit, update owners, and change status of submissions.
+-  **App Definition Retrieval**: Fetch complete app structure and metadata.
+-  **Input Validation**: Built-in validation for IDs, emails, and status objects.
+-  **Extensible Tools**: Modular functions for each operation, easily integrated into agents or scripts.
+-  **Comprehensive Testing**: Includes unit and integration tests.
+
+---
+
+## Installation
+
+```bash
+pip install clappia-tools
+```
+
+Or, for development:
+
+```bash
+git clone https://github.com/clappia-dev/clappia-tools.git
+cd clappia-tools
+pip install -e .[dev]
+```
+
+---
+
+## Configuration
+
+You must provide your Clappia API credentials and workspace information directly when initializing the `ClappiaClient`:
+
+-  `api_key`: Your Clappia API key
+-  `base_url`: The base URL for the Clappia API (e.g., `https://api.clappia.com`)
+-  `workplace_id`: Your Clappia workplace ID
+
+**Example:**
+
+```python
+from clappia_tools import ClappiaClient
+
+client = ClappiaClient(
+    api_key="your-api-key",
+    base_url="https://api.clappia.com",
+    workplace_id="your-workplace-id"
+)
+```
+---
+
+## Usage
+
+### Basic Client Usage
+
+```python
+from clappia_tools import ClappiaClient
+
+client = ClappiaClient(
+    api_key="your-api-key",
+    base_url="https://api.clappia.com",
+    workplace_id="your-workplace-id"
+)
+
+# Create a submission
+result = client.create_submission(
+    app_id="MFX093412",
+    data={"employee_name": "John Doe", "department": "Engineering"},
+    email="user@example.com"
+)
+print(result)
+
+# Edit a submission
+result = client.edit_submission(
+    app_id="MFX093412",
+    submission_id="HGO51464561",
+    data={"department": "Marketing"},
+    email="user@example.com"
+)
+print(result)
+
+# Get app definition
+result = client.get_app_definition(app_id="MFX093412")
+print(result)
+```
+
+### Tool Functions
+
+You can also use the modular tool functions directly:
+
+```python
+from clappia_tools._tools import (
+    create_clappia_submission,
+    edit_clappia_submission,
+    get_app_definition,
+    update_clappia_submission_owners,
+    update_clappia_submission_status,
+)
+
+# Create a submission
+data = {"employee_name": "Jane Doe", "department": "HR"}
+response = create_clappia_submission("MFX093412", data, "user@example.com")
+print(response)
+
+# Update submission owners
+response = update_clappia_submission_owners(
+    "MFX093412", "HGO51464561", "admin@example.com", ["user1@company.com", "user2@company.com"]
+)
+print(response)
+
+# Update submission status
+response = update_clappia_submission_status(
+    "MFX093412", "HGO51464561", "admin@example.com", {"statusName": "Approved", "comments": "Reviewed."}
+)
+print(response)
+```
+
+---
+
+## Available Tools
+
+-  `create_clappia_submission(app_id, data, email)`
+-  `edit_clappia_submission(app_id, submission_id, data, email)`
+-  `get_app_definition(app_id, language="en", strip_html=True, include_tags=True)`
+-  `update_clappia_submission_owners(app_id, submission_id, requesting_user_email_address, email_ids)`
+-  `update_clappia_submission_status(app_id, submission_id, requesting_user_email_address, status)`
+
+See docstrings in each tool for detailed argument and return value descriptions.
+
+---
+
+## Input Validation
+
+-  **App ID**: Must be uppercase letters and numbers (e.g., `MFX093412`).
+-  **Submission ID**: Must be uppercase letters and numbers (e.g., `HGO51464561`).
+-  **Email**: Must be a valid email address.
+-  **Status**: Must be a dictionary with a non-empty `statusName` or `name` field.
+
+Invalid inputs will return descriptive error messages.
+
+---
+
+## Testing
+
+Run all tests (unit and integration):
+
+```bash
+pytest
+```
+
+---
+
+## Contributing
+
+1. Fork the repository and create your branch.
+2. Write clear, well-documented code and tests.
+3. Run `pytest` and ensure all tests pass.
+4. Submit a pull request with a clear description of your changes.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

clappia_api_tools-0.1.5.dist-info/RECORD

@@ -0,0 +1,27 @@
+clappia_api_tools-0.1.5.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/__init__.py,sha256=p5I5RBY9Y6POnuOf4yKbea_yQ0CD7fTUz4JicjbwvBA,519
+clappia_tools/_enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/_enums/enums.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/_models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/_models/model.py,sha256=mIXynyUeIK9KrAcDNKRkAFQExr7lZTAm4Rs_LPveZSU,897
+clappia_tools/_utils/__init__.py,sha256=X7W407Kjb4fCc7OcWqex6X_P893k4qLKi-pdgd-6z60,136
+clappia_tools/_utils/api_utils.py,sha256=_J6e1rdAcbndQeQ9i0QsqpdkwHYR5oKdvdAbBcT0OCg,4711
+clappia_tools/_utils/logging_utils.py,sha256=OAZTKJKBPSXFMMViSXVji2FwJ4mY_jGiMZJ9DAdJY8s,3097
+clappia_tools/_utils/validators.py,sha256=W5yIJnr241ZzPg3LyJerKZs8W0Lj7OzLliKbKXayZqE,4866
+clappia_tools/client/__init__.py,sha256=XQbzWq6BDOWs_7iPHBEYBbh55lhzg1Yw4f_xsIbPWFQ,359
+clappia_tools/client/app_definition_client.py,sha256=ITY_hKD_9yuWvk7Ol-oE2GMtLYDUqHzvWudqGcBq3eg,3789
+clappia_tools/client/app_management_client.py,sha256=7ij7lFKCr5NQ5tFJi65n1zHAEhZwxsxEMGXlL2zyz_4,23835
+clappia_tools/client/base_client.py,sha256=0_R_cFPSCqjNPcG0gHPgBwviUOxlkfSIwVQlgiCi2so,833
+clappia_tools/client/clappia_client.py,sha256=h2zSqhSFHB4Ijh-RaxiRg1CXfyxXWEgNwqj92FJ1N5k,10007
+clappia_tools/client/submission_client.py,sha256=jviQdE40qbqFEhWNX-ToHAvMoy-nqjAGkJQef4D3ihY,14494
+clappia_tools/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/tests/integration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/tests/integration/definition/test_tools_definition.py,sha256=jrzPx8VNPkpqJcfS-NVGAcsEix_u8tWtnwAk_dflJ2A,16572
+clappia_tools/tests/integration/submission/test_tools_submission.py,sha256=vFLQ7T-poPjhvmUvGctsVygqEMbsAyZfpuLroBbTEL0,9796
+clappia_tools/tests/unit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clappia_tools/tests/unit/definition/test_validators.py,sha256=d2QdIoL8mKWN0GSIYW5_4SQhNP-mNAeEmQc5rVpOWiE,7821
+clappia_tools/tests/unit/submission/test_client.py,sha256=uEiz1D0qdS-5C86FMzd1VR_Emp7Cedz6CVbIiMJiuZw,10771
+clappia_api_tools-0.1.5.dist-info/METADATA,sha256=m6rGHe5uvy1k1K9pDH-85PDn6lGDhRbqgoVCJWKBF3Y,6427
+clappia_api_tools-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+clappia_api_tools-0.1.5.dist-info/top_level.txt,sha256=q8xOO-1KTRJwcux9LiCzVLbYG6KrlF1uH6bsQFx3kpo,14
+clappia_api_tools-0.1.5.dist-info/RECORD,,

clappia_api_tools-0.1.5.dist-info/WHEEL

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

clappia_api_tools-0.1.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+clappia_tools

clappia_tools/__init__.py

@@ -0,0 +1,17 @@
+"""
+Clappia Tools - LangChain integration for Clappia API
+
+This package provides a unified client for interacting with Clappia APIs.
+"""
+
+from .client.clappia_client import ClappiaClient
+from .client.app_definition_client import AppDefinitionClient
+from .client.app_management_client import AppManagementClient
+from .client.submission_client import SubmissionClient
+
+__version__ = "0.1.5"
+__all__ = ["ClappiaClient", "AppDefinitionClient", "AppManagementClient", "SubmissionClient"]
+
+
+def __dir__():
+    return __all__

clappia_tools/_models/model.py

@@ -0,0 +1,40 @@
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+@dataclass
+class Field:
+    """Field model for creating an app"""
+    """
+    fieldType: str
+    label: str
+    options: Optional[List[str]] = None
+    """
+
+    fieldType: str
+    label: str
+    options: Optional[List[str]] = None
+    def to_dict(self) -> dict:
+        result = {
+            "fieldType": self.fieldType,
+            "label": self.label,
+        }
+        if self.options is not None:
+            result["options"] = self.options
+        return result
+
+@dataclass
+class Section:
+    """Section model for creating an app"""
+    """
+    sectionName: str
+    fields: List[Field]
+    """
+    
+    sectionName: str
+    fields: List[Field]
+    def to_dict(self) -> dict:
+        return {
+            "sectionName": self.sectionName,
+            "fields": [field.to_dict() for field in self.fields]
+        }

clappia_tools/_utils/__init__.py

@@ -0,0 +1,5 @@
+__all__ = []
+
+from .logging_utils import get_logger
+from .validators import ClappiaInputValidator
+from .api_utils import ClappiaAPIUtils

clappia_tools/_utils/api_utils.py

@@ -0,0 +1,141 @@
+import os
+import json
+import requests
+from typing import Optional, Dict, Any, Tuple
+from clappia_tools._utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class ClappiaAPIUtils:
+    """Utilities for Clappia API interactions"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        workplace_id: str,
+        timeout: int = 30,
+    ):
+        """
+        Initialize API utilities with configurable parameters
+
+        Args:
+            api_key: Clappia API key
+            base_url: API base URL
+            workplace_id: Workplace ID
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.base_url = base_url
+        self.workplace_id = workplace_id
+        self.timeout = timeout
+
+    def validate_environment(self) -> Tuple[bool, str]:
+        """Validate that required configuration is available"""
+        if not self.api_key:
+            return (
+                False,
+                "API key is not configured",
+            )
+        if not self.base_url:
+            return (
+                False,
+                "Base URL is not configured",
+            )
+        if not self.workplace_id:
+            return (
+                False,
+                "Workplace ID is not configured",
+            )
+        return True, ""
+
+    def get_headers(self) -> Dict[str, str]:
+        """Get standard headers for API requests"""
+        return {
+            "x-api-key": self.api_key,
+            "Content-Type": "application/json",
+            "workplaceId": self.workplace_id,
+        }
+
+    def handle_response(
+        self, response: requests.Response
+    ) -> Tuple[bool, Optional[str], Optional[Dict[str, Any]]]:
+        """
+        Handle API response and return structured result
+
+        Returns:
+            Tuple of (success: bool, error_message: str, data: dict)
+        """
+        if response.status_code == 200:
+            try:
+                return True, None, response.json()
+            except json.JSONDecodeError:
+                logger.warning(f"Valid response but invalid JSON: {response.text}")
+                return True, None, {"raw_response": response.text}
+
+        error_message = self._format_error_message(response)
+        return False, error_message, None
+
+    def _format_error_message(self, response: requests.Response) -> str:
+        """Format error message from API response"""
+        if response.status_code in [400, 401, 403, 404]:
+            try:
+                error_data = response.json()
+                return f"API Error ({response.status_code}): {json.dumps(error_data, indent=2)}"
+            except json.JSONDecodeError:
+                return f"API Error ({response.status_code}): {response.text}"
+        else:
+            return f"Unexpected API response ({response.status_code}): {response.text}"
+
+    def make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[bool, Optional[str], Optional[Dict[str, Any]]]:
+        """
+        Make HTTP request to Clappia API
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint (will be appended to base_url)
+            data: Request body data (for POST/PUT requests)
+            params: Query parameters (for GET requests)
+
+        Returns:
+            Tuple of (success: bool, error_message: str, response_data: dict)
+        """
+        env_valid, env_error = self.validate_environment()
+        if not env_valid:
+            return False, f"Configuration error: {env_error}", None
+
+        url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
+        headers = self.get_headers()
+
+        try:
+            logger.info(f"Making {method} request to {url}")
+            if data:
+                logger.debug(f"Request data: {json.dumps(data, indent=2)}")
+
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=data,
+                params=params,
+                timeout=self.timeout,
+            )
+
+            logger.info(f"Response status: {response.status_code}")
+            logger.debug(f"Response body: {response.text}")
+
+            return self.handle_response(response)
+
+        except requests.exceptions.Timeout:
+            return False, f"Request timeout after {self.timeout} seconds", None
+        except requests.exceptions.ConnectionError:
+            return False, "Connection error - unable to reach Clappia API", None
+        except Exception as e:
+            return False, f"Unexpected error: {str(e)}", None

clappia_tools/_utils/logging_utils.py

@@ -0,0 +1,132 @@
+import sys
+from datetime import datetime
+from enum import Enum
+
+
+class bcolors:
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+
+class LogLevel(Enum):
+    DEBUG = 0
+    INFO = 1
+    WARNING = 2
+    ERROR = 3
+    CRITICAL = 4
+
+
+class Logger:
+    def __init__(
+        self,
+        name: str = "Logger",
+        level: LogLevel = LogLevel.INFO,
+        timestamp_format: str = "%Y-%m-%d %H:%M:%S",
+    ):
+        self.name = name
+        self.level = level
+        self.timestamp_format = timestamp_format
+
+        self.colors = {
+            LogLevel.DEBUG: bcolors.OKBLUE,
+            LogLevel.INFO: bcolors.OKGREEN,
+            LogLevel.WARNING: bcolors.WARNING,
+            LogLevel.ERROR: bcolors.FAIL,
+            LogLevel.CRITICAL: bcolors.HEADER,
+        }
+        self.reset_color = bcolors.ENDC
+
+    def _should_log(self, level: LogLevel) -> bool:
+        return level.value >= self.level.value
+
+    def _format_message(self, level: LogLevel, message: str) -> str:
+        timestamp = datetime.now().strftime(self.timestamp_format)
+        return f"[{timestamp}] [{self.name}] [{level.name}] {message}"
+
+    def _log(self, level: LogLevel, message: str):
+        if not self._should_log(level):
+            return
+
+        message_str = str(message)
+        formatted_message = self._format_message(level, message_str)
+
+        supports_color = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+        if supports_color:
+            color = self.colors.get(level, "")
+            colored_message = f"{color}{formatted_message}{self.reset_color}"
+        else:
+            colored_message = formatted_message
+
+        output_stream = (
+            sys.stderr if level.value >= LogLevel.WARNING.value else sys.stdout
+        )
+        print(colored_message, file=output_stream)
+
+    def debug(self, message: str):
+        self._log(LogLevel.DEBUG, message)
+
+    def info(self, message: str):
+        self._log(LogLevel.INFO, message)
+
+    def warning(self, message: str):
+        self._log(LogLevel.WARNING, message)
+
+    def error(self, message: str):
+        self._log(LogLevel.ERROR, message)
+
+    def critical(self, message: str):
+        self._log(LogLevel.CRITICAL, message)
+
+    def set_level(self, level: LogLevel):
+        self.level = level
+
+
+_default_logger = Logger()
+
+
+def get_logger(name: str = "Logger", level: LogLevel = LogLevel.INFO) -> Logger:
+    return Logger(name, level)
+
+
+def debug(message: str):
+    _default_logger.debug(message)
+
+
+def info(message: str):
+    _default_logger.info(message)
+
+
+def warning(message: str):
+    _default_logger.warning(message)
+
+
+def error(message: str):
+    _default_logger.error(message)
+
+
+def critical(message: str):
+    _default_logger.critical(message)
+
+
+def set_level(level: LogLevel):
+    _default_logger.set_level(level)
+
+
+__all__ = [
+    "get_logger",
+    "set_level",
+    "debug",
+    "info",
+    "warning",
+    "error",
+    "critical",
+    "LogLevel",
+]