Skip to content

README.md

Latest commit

 

History

History
210 lines (157 loc) · 4.58 KB

README.md

File metadata and controls

210 lines (157 loc) · 4.58 KB

Workflows CDK

A powerful CDK (Connector Development Kit) for building Stacksync Workflows Connectors with Python and Flask.

Features

  • 🚀 Automatic route discovery and registration file based (like in Next.js!)
  • 🔒 Built-in error handling and Sentry integration
  • 📦 Standardized request/response handling
  • 🛠️ Error management with standardized error handling
  • 🔄 Environment-aware configuration

Installation

pip install workflows-cdk

Quick Start

  1. Create a new project directory:
mkdir my-workflow-connector
cd my-workflow-connector
  1. Install the required dependencies:
pip install workflows-cdk flask pyyaml
  1. Create the basic project structure:
my-workflow-connector/
├── main.py
├── app_config.yaml
├── requirements.txt
└── routes/
    └── hello/
        └── v1/
            └── route.py
  1. Set up your app_config.yaml:
app_settings:
  app_type: "example"
  app_name: "My Workflow Connector"
  app_description: "A simple workflow connector"
  sentry_dsn: "your-sentry-dsn" # Optional
  cors_origins: ["*"]
  routes_directory: "routes"
  debug: true
  host: "0.0.0.0"
  port: 2005
  1. Create your main.py:
from flask import Flask
from workflows_cdk import Router

# Create Flask app
app = Flask("my-workflow-connector")

# Initialize router with configuration
router = Router(app)

# Run the app
if __name__ == "__main__":
    router.run_app(app)
  1. Create your first route in routes/send_message/v1/route.py:
from workflows_cdk import Request, Response, ManagedError
from main import router

@router.route("/execute", methods=["POST"])
def execute():
    """Execute the send message action."""
    request = Request(flask_request)
    data = request.data

    name = data.get("name", "World")
    return Response.success(data={
        "message": f"Hello, {name}!"
    })

Core Components

Router

The Router class is the heart of the CDK, providing:

  • Automatic route discovery based on file system structure
  • Built-in error handling and Sentry integration
  • CORS configuration
  • Health check endpoints
  • API documentation

Request

The Request class wraps Flask's request object, providing:

  • Easy access to request data and credentials
  • Automatic JSON parsing
  • Type-safe access to common properties

Response

The Response class provides standardized response formatting:

  • Success responses with optional metadata
  • Error responses with appropriate status codes
  • Environment-aware error details
  • Sentry integration

ManagedError

The ManagedError class provides structured error handling:

  • Type-safe error creation
  • Automatic Sentry reporting
  • Environment-aware error details
  • Common error types (validation, not found, unauthorized, etc.)

Project Structure

Recommended project structure for a workflow connector:

my-workflow-connector/
├── main.py                 # Application entry point
├── app_config.yaml         # Application configuration
├── requirements.txt        # Python dependencies
├── README.md              # Project documentation
├── Dockerfile             # Container configuration
├── .env                   # Environment variables
└── routes/                # Route modules
    └── action_name/       # Group routes by action
        ├── v1/            # Version 1 of the action
        │   ├── route.py   # Route implementation
        │   └── schema.json # JSON Schema for validation
        └── v2/            # Version 2 of the action
            ├── route.py
            └── schema.json

Error Handling

The CDK provides comprehensive error handling:

from workflows_cdk import ManagedError

# Validation error
raise ManagedError.validation_error(
    error="Invalid input",
    data={"field": "email"}
)

# Not found error
raise ManagedError.not_found(
    resource="User",
    identifier="123"
)

# Authorization error
raise ManagedError.unauthorized(
    message="Invalid API key"
)

# Server error
raise ManagedError.server_error(
    error="Database connection failed"
)

Response Formatting

Standardized response formatting:

from workflows_cdk import Response

# Success response
return Response.success(
    data={"result": "ok"},
    message="Operation completed",
    metadata={"timestamp": "2024-02-17"}
)

# Error response
return Response.error(
    error="Something went wrong",
    status_code=400
)

License

This project is licensed under the Stacksync Connector License (SCL) v1.0.