msaas-forms 0.1.0__tar.gz

msaas_forms-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_forms-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-forms
+Version: 0.1.0
+Summary: Dynamic form builder and submission handler for SaaS applications
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'

msaas_forms-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "msaas-forms"
+version = "0.1.0"
+description = "Dynamic form builder and submission handler for SaaS applications"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+    "fastapi>=0.115.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forms"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_forms-0.1.0/src/forms/__init__.py

@@ -0,0 +1,35 @@
+"""Willian Forms -- Dynamic form builder and submission handler for SaaS applications."""
+
+from forms.config import FormsConfig, get_config, get_forms, init_forms
+from forms.models import (
+    FieldType,
+    FormDefinition,
+    FormField,
+    FormSettings,
+    FormSubmission,
+    ValidationError,
+    ValidationRule,
+    ValidationType,
+)
+from forms.service import FormService
+from forms.store import FormStore, InMemoryFormStore
+from forms.validator import FormValidator
+
+__all__ = [
+    "FieldType",
+    "FormDefinition",
+    "FormField",
+    "FormService",
+    "FormSettings",
+    "FormStore",
+    "FormSubmission",
+    "FormValidator",
+    "FormsConfig",
+    "InMemoryFormStore",
+    "ValidationError",
+    "ValidationRule",
+    "ValidationType",
+    "get_config",
+    "get_forms",
+    "init_forms",
+]

msaas_forms-0.1.0/src/forms/config.py

@@ -0,0 +1,73 @@
+"""Forms module configuration and initialization."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+_config: FormsConfig | None = None
+_service: object | None = None  # Lazy ref to avoid circular import
+
+
+class FormsConfig(BaseModel):
+    """Configuration for the forms module.
+
+    Args:
+        max_fields_per_form: Maximum number of fields allowed in a single form.
+        max_submissions_per_form: Default cap on submissions per form (0 = unlimited).
+        rate_limit_per_minute: Maximum submissions per form per minute.
+    """
+
+    max_fields_per_form: int = 50
+    max_submissions_per_form: int = 0
+    rate_limit_per_minute: int = 60
+
+
+def init_forms(config: FormsConfig | None = None) -> FormsConfig:
+    """Initialize the forms module with the given configuration.
+
+    Args:
+        config: Forms configuration. Uses defaults if None.
+
+    Returns:
+        The active FormsConfig.
+    """
+    global _config, _service
+    _config = config or FormsConfig()
+    _service = None
+    return _config
+
+
+def get_config() -> FormsConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_forms() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Forms module not initialized. Call init_forms() first.")
+    return _config
+
+
+def get_forms():
+    """Return or create the singleton FormService.
+
+    Raises:
+        RuntimeError: If init_forms() has not been called.
+    """
+    global _service
+    if _config is None:
+        raise RuntimeError("Forms module not initialized. Call init_forms() first.")
+    if _service is None:
+        from forms.service import FormService
+        from forms.store import InMemoryFormStore
+
+        _service = FormService(config=_config, store=InMemoryFormStore())
+    return _service
+
+
+def reset() -> None:
+    """Reset module state (useful for testing)."""
+    global _config, _service
+    _config = None
+    _service = None

msaas_forms-0.1.0/src/forms/models.py

@@ -0,0 +1,146 @@
+"""Pydantic models for form definitions, fields, submissions, and validation."""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FieldType(str, enum.Enum):
+    """Supported form field types."""
+
+    TEXT = "text"
+    NUMBER = "number"
+    EMAIL = "email"
+    SELECT = "select"
+    MULTISELECT = "multiselect"
+    CHECKBOX = "checkbox"
+    TEXTAREA = "textarea"
+    DATE = "date"
+    FILE = "file"
+
+
+class ValidationType(str, enum.Enum):
+    """Types of validation rules that can be applied to fields."""
+
+    MIN_LENGTH = "min_length"
+    MAX_LENGTH = "max_length"
+    PATTERN = "pattern"
+    MIN = "min"
+    MAX = "max"
+    CUSTOM = "custom"
+
+
+class ValidationRule(BaseModel):
+    """A single validation constraint for a form field.
+
+    Args:
+        type: The kind of validation (min_length, pattern, etc.).
+        value: The constraint value (number, regex string, etc.).
+        message: Human-readable error message when validation fails.
+    """
+
+    type: ValidationType
+    value: Any
+    message: str = ""
+
+
+class FormField(BaseModel):
+    """Definition of a single field within a form.
+
+    Args:
+        name: Machine-readable field identifier.
+        type: The input type for this field.
+        label: Human-readable label displayed to users.
+        required: Whether the field must be filled.
+        placeholder: Placeholder text shown in empty inputs.
+        validation_rules: List of validation constraints.
+        options: Choices for select/multiselect fields.
+        order: Display order (lower numbers appear first).
+    """
+
+    name: str
+    type: FieldType = FieldType.TEXT
+    label: str = ""
+    required: bool = False
+    placeholder: str = ""
+    validation_rules: list[ValidationRule] = Field(default_factory=list)
+    options: list[str] = Field(default_factory=list)
+    order: int = 0
+
+
+class FormSettings(BaseModel):
+    """Configuration options for a form's behavior.
+
+    Args:
+        allow_anonymous: Whether unauthenticated users can submit.
+        max_submissions: Maximum total submissions (0 = unlimited).
+        close_after_date: ISO datetime after which submissions are rejected.
+        notification_emails: Email addresses to notify on new submissions.
+    """
+
+    allow_anonymous: bool = True
+    max_submissions: int = 0
+    close_after_date: datetime | None = None
+    notification_emails: list[str] = Field(default_factory=list)
+
+
+class FormDefinition(BaseModel):
+    """A complete form definition with fields and settings.
+
+    Args:
+        id: Unique form identifier.
+        name: Human-readable form name.
+        description: Optional description of the form's purpose.
+        fields: Ordered list of form fields.
+        settings: Form behavior configuration.
+        created_at: When the form was created.
+        updated_at: When the form was last modified.
+        published: Whether the form accepts submissions.
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    fields: list[FormField] = Field(default_factory=list)
+    settings: FormSettings = Field(default_factory=FormSettings)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    published: bool = False
+
+
+class FormSubmission(BaseModel):
+    """A single submission (response) to a form.
+
+    Args:
+        id: Unique submission identifier.
+        form_id: The form this submission belongs to.
+        data: Field name to value mapping of submitted answers.
+        submitted_by: Identifier of the user who submitted (None if anonymous).
+        submitted_at: When the submission was recorded.
+        ip_address: IP address of the submitter.
+    """
+
+    id: str
+    form_id: str
+    data: dict[str, Any] = Field(default_factory=dict)
+    submitted_by: str | None = None
+    submitted_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    ip_address: str | None = None
+
+
+class ValidationError(BaseModel):
+    """A structured validation error tied to a specific field.
+
+    Args:
+        field: The field name that failed validation.
+        message: Human-readable description of the failure.
+        rule_type: The validation rule type that was violated.
+    """
+
+    field: str
+    message: str
+    rule_type: str | None = None

msaas_forms-0.1.0/src/forms/router.py

@@ -0,0 +1,178 @@
+"""FastAPI router factory for form management and submission endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+
+from forms.config import get_forms
+from forms.models import (
+    FormDefinition,
+    FormField,
+    FormSettings,
+    FormSubmission,
+)
+from errors import AuthorizationError, BusinessLogicError, ConflictError, NotFoundError, ValidationError
+from api_core.responses import ApiResponse, PaginatedResponse
+
+
+class CreateFormRequest(BaseModel):
+    """Request body for creating a new form."""
+
+    name: str
+    description: str = ""
+    fields: list[FormField] = Field(default_factory=list)
+    settings: FormSettings = Field(default_factory=FormSettings)
+
+
+class UpdateFormRequest(BaseModel):
+    """Request body for updating an existing form."""
+
+    name: str | None = None
+    description: str | None = None
+    fields: list[FormField] | None = None
+    settings: FormSettings | None = None
+
+
+class SubmitFormRequest(BaseModel):
+    """Request body for submitting a response to a form."""
+
+    data: dict[str, Any]
+    submitted_by: str | None = None
+
+
+class FormStatsResponse(BaseModel):
+    """Response body for form submission statistics."""
+
+    form_id: str
+    total_submissions: int
+    last_submission_at: str | None
+    published: bool
+
+
+def create_forms_router(
+    *,
+    prefix: str = "",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router with form management and submission endpoints.
+
+    The router uses get_forms() to obtain the FormService singleton,
+    so init_forms() must be called before any requests are handled.
+
+    Args:
+        prefix: URL prefix for all routes.
+        tags: OpenAPI tags.
+
+    Returns:
+        A configured APIRouter.
+    """
+    router = APIRouter(prefix=prefix, tags=tags or ["forms"])
+
+    @router.post("/forms", response_model=FormDefinition, status_code=201)
+    async def create_form(body: CreateFormRequest) -> FormDefinition:
+        """Create a new form definition."""
+        service = get_forms()
+        try:
+            return await service.create_form(
+                name=body.name,
+                description=body.description,
+                fields=body.fields,
+                settings=body.settings,
+            )
+        except ValueError as exc:
+            raise ValidationError(str(exc))
+
+    @router.get("/forms", response_model=list[FormDefinition])
+    async def list_forms(
+        published_only: bool = Query(False),
+        offset: int = Query(0, ge=0),
+        limit: int = Query(100, ge=1, le=1000),
+    ) -> list[FormDefinition]:
+        """List form definitions."""
+        service = get_forms()
+        return await service._store.list_forms(
+            published_only=published_only, offset=offset, limit=limit
+        )
+
+    @router.get("/forms/{form_id}", response_model=FormDefinition)
+    async def get_form(form_id: str) -> FormDefinition:
+        """Get a form definition by ID."""
+        service = get_forms()
+        form = await service._store.get_form(form_id)
+        if form is None:
+            raise NotFoundError("Form not found.")
+        return form
+
+    @router.put("/forms/{form_id}", response_model=FormDefinition)
+    async def update_form(form_id: str, body: UpdateFormRequest) -> FormDefinition:
+        """Update an existing form definition."""
+        service = get_forms()
+        try:
+            return await service.update_form(
+                form_id,
+                name=body.name,
+                description=body.description,
+                fields=body.fields,
+                settings=body.settings,
+            )
+        except KeyError:
+            raise NotFoundError("Form not found.")
+        except ValueError as exc:
+            raise ValidationError(str(exc))
+
+    @router.post("/forms/{form_id}/publish", response_model=FormDefinition)
+    async def publish_form(form_id: str) -> FormDefinition:
+        """Publish a form so it accepts submissions."""
+        service = get_forms()
+        try:
+            return await service.publish_form(form_id)
+        except KeyError:
+            raise NotFoundError("Form not found.")
+        except ValueError as exc:
+            raise ValidationError(str(exc))
+
+    @router.post("/forms/{form_id}/submit", response_model=FormSubmission, status_code=201)
+    async def submit_form(
+        form_id: str, body: SubmitFormRequest, request: Request
+    ) -> FormSubmission:
+        """Submit a response to a published form."""
+        service = get_forms()
+        ip = request.client.host if request.client else None
+        try:
+            return await service.submit_form(
+                form_id,
+                body.data,
+                submitted_by=body.submitted_by,
+                ip_address=ip,
+            )
+        except KeyError:
+            raise NotFoundError("Form not found.")
+        except PermissionError as exc:
+            raise AuthorizationError(str(exc))
+        except ValueError as exc:
+            raise ValidationError(str(exc))
+
+    @router.get("/forms/{form_id}/submissions", response_model=list[FormSubmission])
+    async def get_submissions(
+        form_id: str,
+        offset: int = Query(0, ge=0),
+        limit: int = Query(100, ge=1, le=1000),
+    ) -> list[FormSubmission]:
+        """List submissions for a form."""
+        service = get_forms()
+        return await service.get_submissions(form_id, offset=offset, limit=limit)
+
+    @router.get("/forms/{form_id}/stats", response_model=FormStatsResponse)
+    async def get_stats(form_id: str) -> FormStatsResponse:
+        """Get submission statistics for a form."""
+        service = get_forms()
+        try:
+            stats = await service.get_stats(form_id)
+            return FormStatsResponse(**stats)
+        except KeyError:
+            raise NotFoundError("Form not found.")
+
+    return router