swipeflow-api 1.1.0__py3-none-any.whl

swipeflow_api/__init__.py

@@ -0,0 +1,63 @@
+"""SwipeFlow Python SDK for automation workflow approvals.
+
+A Pythonic SDK for integrating SwipeFlow approval workflows into your applications.
+
+Example:
+    >>> from swipeflow_api import SwipeFlowClient
+    >>> client = SwipeFlowClient(api_key="your-api-key")
+    >>> projects = client.projects.list()
+    >>> items = client.items.list(project_id="project-123")
+"""
+
+__version__ = "1.1.0"
+__author__ = "SwipeFlow"
+__email__ = "support@swipeflow.io"
+__license__ = "ISC"
+
+from .client import SwipeFlowClient
+from .models import (
+    User,
+    Project,
+    Item,
+    ItemVersion,
+    Decision,
+    Webhook,
+    WebhookEvent,
+    ItemStatus,
+    DecisionType,
+    ProjectRole,
+    ContentType,
+    ApiKey,
+)
+from .exceptions import (
+    SwipeFlowError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+__all__ = [
+    "SwipeFlowClient",
+    # Models
+    "User",
+    "Project",
+    "Item",
+    "ItemVersion",
+    "Decision",
+    "Webhook",
+    "WebhookEvent",
+    "ItemStatus",
+    "DecisionType",
+    "ProjectRole",
+    "ContentType",
+    "ApiKey",
+    # Exceptions
+    "SwipeFlowError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+]

swipeflow_api/client.py

@@ -0,0 +1,161 @@
+"""Main SwipeFlow API client."""
+
+from typing import Optional
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .resources import ProjectsResource, ItemsResource, WebhooksResource, ApiKeysResource, AuthResource
+from .exceptions import raise_for_status
+
+
+class SwipeFlowClient:
+    """Main client for interacting with the SwipeFlow API.
+
+    Example:
+        >>> client = SwipeFlowClient(api_key="your-api-key")
+        >>> projects = client.projects.list()
+        >>> items = client.items.list(project_id="project-123")
+    """
+
+    DEFAULT_BASE_URL = "https://api.swipeflow.io"
+    DEFAULT_TIMEOUT = 30
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        verify_ssl: bool = True,
+    ):
+        """Initialize SwipeFlow API client.
+
+        Args:
+            api_key: API key for authentication. If not provided, will look for
+                    SWIPEFLOW_API_KEY environment variable.
+            base_url: Base URL for the API. Defaults to production API.
+            timeout: Request timeout in seconds.
+            verify_ssl: Whether to verify SSL certificates.
+
+        Raises:
+            ValueError: If no API key is provided and environment variable not set.
+        """
+        import os
+
+        self.api_key = api_key or os.getenv("SWIPEFLOW_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key not provided. Pass it to SwipeFlowClient(api_key='...') "
+                "or set SWIPEFLOW_API_KEY environment variable."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+
+        self._session = self._create_session()
+
+        # Initialize resources
+        self.projects = ProjectsResource(self)
+        self.items = ItemsResource(self)
+        self.webhooks = WebhooksResource(self)
+        self.api_keys = ApiKeysResource(self)
+        self.auth = AuthResource(self)
+
+    def _create_session(self) -> requests.Session:
+        """Create a requests session with retry strategy.
+
+        Returns:
+            Configured requests session
+        """
+        session = requests.Session()
+
+        # Set up retry strategy
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "OPTIONS", "POST", "PUT", "DELETE"],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+
+        # Set headers
+        session.headers.update(
+            {
+                "X-API-Key": self.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "swipeflow-python-sdk/1.1.0",
+            }
+        )
+
+        return session
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        json_data: Optional[dict] = None,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> dict:
+        """Make an HTTP request to the API.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            endpoint: API endpoint (without base URL)
+            json_data: JSON body data
+            params: Query parameters
+            headers: Additional headers
+
+        Returns:
+            Response JSON as dictionary
+
+        Raises:
+            Various SwipeFlowError subclasses depending on response
+        """
+        url = f"{self.base_url}{endpoint}"
+
+        req_headers = headers or {}
+
+        response = self._session.request(
+            method=method,
+            url=url,
+            json=json_data,
+            params=params,
+            headers=req_headers,
+            timeout=self.timeout,
+            verify=self.verify_ssl,
+        )
+
+        # Handle errors
+        if response.status_code >= 400:
+            try:
+                error_data = response.json()
+                message = error_data.get("error", response.text)
+                error_code = error_data.get("code")
+                details = error_data.get("details")
+            except Exception:
+                message = response.text or f"HTTP {response.status_code}"
+                error_code = None
+                details = None
+
+            raise_for_status(response.status_code, message, error_code, details)
+
+        # Handle successful response
+        if response.text:
+            return response.json()
+        return {}
+
+    def close(self) -> None:
+        """Close the client session."""
+        self._session.close()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

swipeflow_api/exceptions.py

@@ -0,0 +1,110 @@
+"""Exception classes for SwipeFlow API client."""
+
+from typing import Any, Dict, Optional
+
+
+class SwipeFlowError(Exception):
+    """Base exception for all SwipeFlow API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.details = details or {}
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format the error message."""
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        return " ".join(parts)
+
+
+class AuthenticationError(SwipeFlowError):
+    """Raised when authentication fails (401 Unauthorized)."""
+
+    pass
+
+
+class AuthorizationError(SwipeFlowError):
+    """Raised when user lacks permissions (403 Forbidden)."""
+
+    pass
+
+
+class NotFoundError(SwipeFlowError):
+    """Raised when a resource is not found (404 Not Found)."""
+
+    pass
+
+
+class ValidationError(SwipeFlowError):
+    """Raised when request validation fails (400 Bad Request)."""
+
+    pass
+
+
+class ConflictError(SwipeFlowError):
+    """Raised when a resource conflict occurs (409 Conflict)."""
+
+    pass
+
+
+class ServerError(SwipeFlowError):
+    """Raised when the server encounters an error (5xx)."""
+
+    pass
+
+
+class NetworkError(SwipeFlowError):
+    """Raised when a network error occurs."""
+
+    pass
+
+
+def raise_for_status(
+    status_code: int,
+    message: str,
+    error_code: Optional[str] = None,
+    details: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Raise appropriate exception based on status code.
+
+    Args:
+        status_code: HTTP status code
+        message: Error message
+        error_code: API-specific error code
+        details: Additional error details
+
+    Raises:
+        AuthenticationError: For 401 responses
+        AuthorizationError: For 403 responses
+        NotFoundError: For 404 responses
+        ValidationError: For 400 responses
+        ConflictError: For 409 responses
+        ServerError: For 5xx responses
+        SwipeFlowError: For other errors
+    """
+    if status_code == 400:
+        raise ValidationError(message, status_code, error_code, details)
+    elif status_code == 401:
+        raise AuthenticationError(message, status_code, error_code, details)
+    elif status_code == 403:
+        raise AuthorizationError(message, status_code, error_code, details)
+    elif status_code == 404:
+        raise NotFoundError(message, status_code, error_code, details)
+    elif status_code == 409:
+        raise ConflictError(message, status_code, error_code, details)
+    elif status_code >= 500:
+        raise ServerError(message, status_code, error_code, details)
+    else:
+        raise SwipeFlowError(message, status_code, error_code, details)

swipeflow_api/models.py

@@ -0,0 +1,211 @@
+"""Pydantic models for SwipeFlow API resources."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ItemStatus(str, Enum):
+    """Status of an item."""
+
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    CHANGE_REQUESTED = "CHANGE_REQUESTED"
+    PROCESSED = "PROCESSED"
+
+
+class DecisionType(str, Enum):
+    """Type of decision on an item."""
+
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    CHANGE_REQUESTED = "CHANGE_REQUESTED"
+
+
+class ProjectRole(str, Enum):
+    """Role in a project."""
+
+    OWNER = "OWNER"
+    ADMIN = "ADMIN"
+    EDITOR = "EDITOR"
+    VIEWER = "VIEWER"
+
+
+class ContentType(str, Enum):
+    """Type of content."""
+
+    TEXT = "TEXT"
+    HTML = "HTML"
+    IMAGE = "IMAGE"
+    VIDEO = "VIDEO"
+    AUDIO = "AUDIO"
+
+
+class WebhookEvent(str, Enum):
+    """Types of webhook events."""
+
+    ITEM_CREATED = "item.created"
+    ITEM_UPDATED = "item.updated"
+    ITEM_DELETED = "item.deleted"
+    ITEM_APPROVED = "item.approved"
+    ITEM_REJECTED = "item.rejected"
+    ITEM_CHANGE_REQUESTED = "item.change_requested"
+    ITEM_PROCESSED = "item.processed"
+    PROJECT_TRIGGER = "project.trigger"
+
+
+class User(BaseModel):
+    """User model."""
+
+    id: str = Field(..., description="User ID")
+    email: str = Field(..., description="Email address")
+    name: Optional[str] = Field(None, description="User's full name")
+    avatar_url: Optional[str] = Field(None, description="Avatar URL")
+    created_at: datetime = Field(..., description="Account creation time")
+    updated_at: datetime = Field(..., description="Last update time")
+
+    class Config:
+        use_enum_values = True
+
+
+class ProjectMember(BaseModel):
+    """Project member information."""
+
+    user_id: str = Field(..., description="User ID")
+    role: ProjectRole = Field(..., description="Role in the project")
+    joined_at: datetime = Field(..., description="When user joined")
+
+    class Config:
+        use_enum_values = True
+
+
+class Project(BaseModel):
+    """Project model."""
+
+    id: str = Field(..., description="Project ID")
+    name: str = Field(..., description="Project name")
+    description: Optional[str] = Field(None, description="Project description")
+    owner_id: str = Field(..., description="Owner user ID")
+    members: List[ProjectMember] = Field(default_factory=list, description="Project members")
+    item_count: int = Field(default=0, description="Number of items")
+    webhook_count: int = Field(default=0, description="Number of webhooks")
+    created_at: datetime = Field(..., description="Creation time")
+    updated_at: datetime = Field(..., description="Last update time")
+
+    class Config:
+        use_enum_values = True
+
+
+class ItemContent(BaseModel):
+    """Content of an item."""
+
+    type: ContentType = Field(..., description="Content type")
+    data: Dict[str, Any] = Field(default_factory=dict, description="Content data")
+    text: Optional[str] = Field(None, description="Text representation")
+    url: Optional[str] = Field(None, description="URL for media content")
+
+    class Config:
+        use_enum_values = True
+
+
+class Decision(BaseModel):
+    """Decision on an item."""
+
+    id: str = Field(..., description="Decision ID")
+    type: DecisionType = Field(..., description="Decision type")
+    decided_by: str = Field(..., description="User ID who decided")
+    decided_at: datetime = Field(..., description="When decision was made")
+    comment: Optional[str] = Field(None, description="Optional comment")
+
+    class Config:
+        use_enum_values = True
+
+
+class ItemVersion(BaseModel):
+    """Version history of an item."""
+
+    id: str = Field(..., description="Version ID")
+    item_id: str = Field(..., description="Item ID")
+    version_number: int = Field(..., description="Version number")
+    content: ItemContent = Field(..., description="Content at this version")
+    created_at: datetime = Field(..., description="When this version was created")
+
+    class Config:
+        use_enum_values = True
+
+
+class Item(BaseModel):
+    """Item model."""
+
+    id: str = Field(..., description="Item ID")
+    project_id: str = Field(..., description="Project ID")
+    title: str = Field(..., description="Item title")
+    content: ItemContent = Field(..., description="Item content")
+    status: ItemStatus = Field(..., description="Current status")
+    decisions: List[Decision] = Field(default_factory=list, description="Decisions made on this item")
+    version: int = Field(default=1, description="Current version number")
+    created_by: str = Field(..., description="User ID who created")
+    created_at: datetime = Field(..., description="Creation time")
+    updated_at: datetime = Field(..., description="Last update time")
+    processed_at: Optional[datetime] = Field(None, description="When item was processed")
+
+    class Config:
+        use_enum_values = True
+
+
+class Webhook(BaseModel):
+    """Webhook model."""
+
+    id: str = Field(..., description="Webhook ID")
+    project_id: str = Field(..., description="Project ID")
+    name: str = Field(..., description="Webhook name")
+    url: str = Field(..., description="Webhook URL")
+    type: str = Field(..., description="Webhook type (user or dynamic)")
+    events: List[WebhookEvent] = Field(..., description="Events this webhook subscribes to")
+    active: bool = Field(default=True, description="Whether webhook is active")
+    integration_provider: Optional[str] = Field(None, description="Integration provider")
+    created_at: datetime = Field(..., description="Creation time")
+    updated_at: datetime = Field(..., description="Last update time")
+
+    class Config:
+        use_enum_values = True
+
+
+class ApiKey(BaseModel):
+    """API key model."""
+
+    id: str = Field(..., description="API key ID")
+    name: str = Field(..., description="Key name")
+    key: Optional[str] = Field(None, description="The actual key (only on creation)")
+    last_used_at: Optional[datetime] = Field(None, description="Last time key was used")
+    created_at: datetime = Field(..., description="Creation time")
+
+    class Config:
+        use_enum_values = True
+
+
+class PaginatedResponse(BaseModel):
+    """Paginated response wrapper."""
+
+    items: List[Dict[str, Any]] = Field(default_factory=list, description="Items in this page")
+    total: int = Field(default=0, description="Total number of items")
+    page: int = Field(default=1, description="Current page number")
+    per_page: int = Field(default=20, description="Items per page")
+    has_more: bool = Field(default=False, description="Whether more items exist")
+
+    class Config:
+        use_enum_values = True
+
+
+class ErrorResponse(BaseModel):
+    """Error response model."""
+
+    error: str = Field(..., description="Error message")
+    code: Optional[str] = Field(None, description="Error code")
+    details: Optional[Dict[str, Any]] = Field(None, description="Additional details")
+
+    class Config:
+        use_enum_values = True