swipeflow-api 1.1.0__tar.gz

swipeflow_api-1.1.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 SwipeFlow
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

swipeflow_api-1.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include swipeflow_api py.typed

swipeflow_api-1.1.0/PKG-INFO

@@ -0,0 +1,568 @@
+Metadata-Version: 2.4
+Name: swipeflow-api
+Version: 1.1.0
+Summary: Python SDK for SwipeFlow API - Add manual approval steps to your workflows with a Tinder-like swiping interface
+Home-page: https://github.com/swipeflow/swipeflow
+Author: SwipeFlow
+Author-email: SwipeFlow <support@swipeflow.io>
+License: ISC
+Project-URL: Homepage, https://swipeflow.io
+Project-URL: Documentation, https://swipeflow.io/docs
+Project-URL: Repository, https://github.com/swipeflow/swipeflow-api-py
+Project-URL: Issue Tracker, https://github.com/swipeflow/swipeflow-api-py/issues
+Keywords: swipeflow,api,sdk,automation,approval,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+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
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: typing-extensions>=4.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# SwipeFlow Python SDK
+
+![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)
+![License](https://img.shields.io/badge/license-ISC-green.svg)
+![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)
+
+A pythonic, auto-generated SDK for the SwipeFlow API. Add manual approval steps to your automation workflows with a Tinder-like swiping interface.
+
+## Features
+
+- 🚀 **Simple & Pythonic** - Intuitive API that follows Python conventions
+- 🔄 **Auto-Generated** - Built from OpenAPI spec for accuracy and consistency
+- 📦 **Fully Typed** - Complete type hints for IDE autocomplete and type checking
+- ⚡ **Async Ready** - Easy to extend with async/await patterns
+- 🛡️ **Error Handling** - Custom exceptions for different error scenarios
+- 🔑 **Multiple Auth** - Supports API keys and JWT tokens
+- 📋 **Well Documented** - Comprehensive docstrings and examples
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install swipeflow-api-py
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from swipeflow_api import SwipeFlowClient
+
+# Initialize client
+client = SwipeFlowClient(api_key="your-api-key")
+
+# List projects
+projects = client.projects.list()
+for project in projects:
+    print(f"Project: {project['name']}")
+
+# Create a new item
+item = client.items.create(
+    project_id="project-123",
+    title="Approve new user signup",
+    content={
+        "type": "TEXT",
+        "data": {"message": "New user John Doe signed up"}
+    }
+)
+print(f"Item created: {item['id']}")
+
+# Approve an item
+client.items.approve(
+    project_id="project-123",
+    item_id=item['id'],
+    comment="User verified"
+)
+```
+
+### Environment Variable
+
+Set the API key as an environment variable instead of passing it directly:
+
+```bash
+export SWIPEFLOW_API_KEY="your-api-key"
+```
+
+Then initialize without the key:
+
+```python
+client = SwipeFlowClient()
+```
+
+### Context Manager
+
+Use the client as a context manager to automatically close connections:
+
+```python
+with SwipeFlowClient(api_key="your-api-key") as client:
+    projects = client.projects.list()
+```
+
+## API Resources
+
+### Projects
+
+```python
+# List projects
+projects = client.projects.list(skip=0, limit=20)
+
+# Get a specific project
+project = client.projects.get("project-id")
+
+# Create a new project
+project = client.projects.create(
+    name="My Project",
+    description="Project description"
+)
+
+# Update a project
+updated = client.projects.update(
+    project_id="project-id",
+    name="Updated Name"
+)
+
+# Delete a project
+client.projects.delete("project-id")
+
+# Add a member to project
+client.projects.add_member(
+    project_id="project-id",
+    user_id="user-id",
+    role="EDITOR"  # OWNER, ADMIN, EDITOR, VIEWER
+)
+
+# Remove a member
+client.projects.remove_member("project-id", "user-id")
+```
+
+### Items
+
+```python
+# List items in a project
+items = client.items.list(
+    project_id="project-id",
+    status="PENDING",  # Optional: filter by status
+    skip=0,
+    limit=20
+)
+
+# Get a specific item
+item = client.items.get("project-id", "item-id")
+
+# Create an item
+item = client.items.create(
+    project_id="project-id",
+    title="Review request",
+    content={
+        "type": "TEXT",
+        "data": {"message": "Please review this document"}
+    }
+)
+
+# Update an item
+updated = client.items.update(
+    project_id="project-id",
+    item_id="item-id",
+    title="Updated title"
+)
+
+# Delete an item
+client.items.delete("project-id", "item-id")
+
+# Approve an item
+client.items.approve(
+    project_id="project-id",
+    item_id="item-id",
+    comment="Looks good!"
+)
+
+# Reject an item
+client.items.reject(
+    project_id="project-id",
+    item_id="item-id",
+    comment="Needs revision"
+)
+
+# Request changes
+client.items.request_changes(
+    project_id="project-id",
+    item_id="item-id",
+    comment="Please update section 2"
+)
+
+# Get item version history
+versions = client.items.get_versions("project-id", "item-id")
+```
+
+### Webhooks
+
+```python
+# List webhooks
+webhooks = client.webhooks.list("project-id")
+
+# Get a webhook
+webhook = client.webhooks.get("project-id", "webhook-id")
+
+# Create a webhook
+webhook = client.webhooks.create(
+    project_id="project-id",
+    name="My Webhook",
+    url="https://example.com/webhook",
+    events=["item.created", "item.approved", "item.rejected"]
+)
+
+# Update a webhook
+updated = client.webhooks.update(
+    project_id="project-id",
+    webhook_id="webhook-id",
+    name="Updated name",
+    active=True
+)
+
+# Delete a webhook
+client.webhooks.delete("project-id", "webhook-id")
+
+# Test a webhook
+result = client.webhooks.test("project-id", "webhook-id")
+```
+
+### API Keys
+
+```python
+# List API keys
+keys = client.api_keys.list()
+
+# Create a new API key
+key = client.api_keys.create(name="Production Key")
+print(f"Key: {key['key']}")  # Save this securely!
+
+# Delete an API key
+client.api_keys.delete("key-id")
+```
+
+### Authentication
+
+```python
+# Get current user profile
+profile = client.auth.get_profile()
+
+# Update profile
+updated = client.auth.update_profile(
+    name="John Doe",
+    avatar_url="https://example.com/avatar.jpg"
+)
+```
+
+## Error Handling
+
+The SDK provides specific exception classes for different error scenarios:
+
+```python
+from swipeflow_api import (
+    SwipeFlowError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+try:
+    client.items.get("project-id", "item-id")
+except NotFoundError as e:
+    print(f"Item not found: {e.message}")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e.message}")
+except SwipeFlowError as e:
+    print(f"API error: {e.message}")
+```
+
+## Models
+
+The SDK includes Pydantic models for type safety:
+
+```python
+from swipeflow_api.models import (
+    Item,
+    Project,
+    User,
+    Webhook,
+    ItemStatus,
+    DecisionType,
+    ProjectRole,
+    ContentType,
+    WebhookEvent,
+)
+
+# Models are used for type hints
+def process_item(item: Item) -> None:
+    print(f"Processing {item.title} (status: {item.status})")
+```
+
+## Advanced Configuration
+
+### Custom Base URL
+
+```python
+client = SwipeFlowClient(
+    api_key="your-api-key",
+    base_url="https://staging-api.swipeflow.io"
+)
+```
+
+### Timeout and SSL
+
+```python
+client = SwipeFlowClient(
+    api_key="your-api-key",
+    timeout=60,
+    verify_ssl=True  # Set to False only in development!
+)
+```
+
+### Direct Request Method
+
+For advanced use cases, access the underlying request method:
+
+```python
+response = client.request(
+    method="POST",
+    endpoint="/v1/projects/123/items",
+    json_data={"title": "Custom item"},
+    params={"custom": "param"}
+)
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/swipeflow/swipeflow.git
+cd sdk/swipeflow-py-api
+pip install -e ".[dev]"
+```
+
+### Code Quality
+
+```bash
+# Format code
+black swipeflow_api/
+
+# Sort imports
+isort swipeflow_api/
+
+# Lint
+flake8 swipeflow_api/
+
+# Type checking
+mypy swipeflow_api/
+
+# Run tests
+pytest tests/
+
+# Generate coverage report
+pytest --cov=swipeflow_api tests/
+```
+
+### Regenerate from OpenAPI
+
+The SDK can be regenerated from the backend's OpenAPI spec:
+
+```bash
+# Using Python
+python scripts/generate.py
+
+# Using bash
+bash scripts/generate.sh
+```
+
+## Publishing
+
+### Build Package
+
+```bash
+python -m build
+```
+
+### Publish to PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## Architecture
+
+### Project Structure
+
+```
+swipeflow-py-api/
+├── swipeflow_api/          # Main package
+│   ├── __init__.py         # Public API
+│   ├── client.py           # Main client
+│   ├── resources.py        # Resource classes
+│   ├── models.py           # Pydantic models
+│   ├── exceptions.py       # Exception classes
+│   └── generated/          # Auto-generated code (from OpenAPI)
+├── scripts/
+│   ├── generate.py         # Generation script
+│   └── generate.sh         # Bash generation script
+├── tests/                  # Test suite
+├── setup.py               # Package setup
+├── pyproject.toml         # Modern Python packaging
+└── README.md             # This file
+```
+
+### Auto-Generation
+
+The client is auto-generated from the OpenAPI spec (`backend/openapi.json`) using OpenAPI Generator. This ensures:
+
+- ✅ Consistency with backend API
+- ✅ Type-safe models
+- ✅ Complete API coverage
+- ✅ Automatic updates as API evolves
+
+The SDK provides a pythonic wrapper (`client.py`, `resources.py`) on top of generated code for better developer experience.
+
+## Examples
+
+### Batch Process Items
+
+```python
+client = SwipeFlowClient(api_key="key")
+
+# Get all pending items
+items = client.items.list(
+    project_id="project-123",
+    status="PENDING",
+    limit=100
+)
+
+# Process them
+for item in items:
+    if "urgent" in item.get("title", "").lower():
+        client.items.approve(
+            project_id="project-123",
+            item_id=item["id"],
+            comment="Urgent - approved"
+        )
+```
+
+### Setup Webhooks
+
+```python
+# Create webhook for all approval events
+client.webhooks.create(
+    project_id="project-123",
+    name="Approval Events",
+    url="https://myapp.com/webhooks/approvals",
+    events=[
+        "item.approved",
+        "item.rejected",
+        "item.change_requested"
+    ]
+)
+```
+
+### Monitor Project
+
+```python
+project = client.projects.get("project-123")
+print(f"Project: {project['name']}")
+print(f"Members: {len(project.get('members', []))}")
+print(f"Items: {project.get('item_count', 0)}")
+print(f"Webhooks: {project.get('webhook_count', 0)}")
+```
+
+## Troubleshooting
+
+### "API key not provided"
+
+Make sure you're passing the API key or setting the `SWIPEFLOW_API_KEY` environment variable:
+
+```python
+# Option 1: Pass directly
+client = SwipeFlowClient(api_key="sk_test_...")
+
+# Option 2: Environment variable
+export SWIPEFLOW_API_KEY="sk_test_..."
+client = SwipeFlowClient()
+```
+
+### Network Errors
+
+The client includes automatic retry logic for transient failures. For persistent issues:
+
+```python
+# Increase timeout
+client = SwipeFlowClient(api_key="key", timeout=60)
+
+# Check API status
+# Visit https://status.swipeflow.io/
+```
+
+### Type Checking Issues
+
+Ensure you're using Python 3.8+ and install type stubs:
+
+```bash
+pip install types-requests
+```
+
+## Support
+
+- 📖 [Documentation](https://docs.swipeflow.io)
+- 🐛 [Report Issues](https://github.com/swipeflow/swipeflow/issues)
+- 💬 [Discussions](https://github.com/swipeflow/swipeflow/discussions)
+- 📧 [Email](mailto:support@swipeflow.io)
+
+## License
+
+ISC License - See LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please read our [contributing guidelines](../../CONTRIBUTING.md) first.
+
+---
+
+**Made with ❤️ by [SwipeFlow](https://swipeflow.io)**