msaas-forms 0.1.0__py3-none-any.whl

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",
+]

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

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

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

forms/service.py

@@ -0,0 +1,235 @@
+"""Form service for orchestrating form lifecycle and submissions."""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Any
+
+from forms.config import FormsConfig
+from forms.models import (
+    FormDefinition,
+    FormField,
+    FormSettings,
+    FormSubmission,
+    ValidationError,
+)
+from forms.store import FormStore
+from forms.validator import FormValidator
+from errors import NotFoundError, ValidationError
+
+logger = logging.getLogger(__name__)
+
+
+class FormService:
+    """Orchestrates form creation, updates, publishing, and submissions.
+
+    Args:
+        config: Module configuration.
+        store: Storage backend for forms and submissions.
+        validator: Submission validator. Created automatically if None.
+    """
+
+    def __init__(
+        self,
+        config: FormsConfig,
+        store: FormStore,
+        validator: FormValidator | None = None,
+    ) -> None:
+        self._config = config
+        self._store = store
+        self._validator = validator or FormValidator()
+        self._rate_limiter: dict[str, list[float]] = defaultdict(list)
+
+    @property
+    def validator(self) -> FormValidator:
+        """Access the underlying form validator (e.g. to register custom hooks)."""
+        return self._validator
+
+    async def create_form(
+        self,
+        *,
+        name: str,
+        description: str = "",
+        fields: list[FormField] | None = None,
+        settings: FormSettings | None = None,
+    ) -> FormDefinition:
+        """Create a new form definition.
+
+        Raises ValueError if field count exceeds max_fields_per_form.
+        """
+        fields = fields or []
+        if len(fields) > self._config.max_fields_per_form:
+            raise ValidationError(
+                f"Too many fields: {len(fields)} > {self._config.max_fields_per_form}"
+            )
+
+        now = datetime.now(timezone.utc)
+        form = FormDefinition(
+            id=str(uuid.uuid4()),
+            name=name,
+            description=description,
+            fields=fields,
+            settings=settings or FormSettings(),
+            created_at=now,
+            updated_at=now,
+        )
+        await self._store.save_form(form)
+        logger.info("Form created: id=%s name=%s", form.id, form.name)
+        return form
+
+    async def update_form(
+        self,
+        form_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        fields: list[FormField] | None = None,
+        settings: FormSettings | None = None,
+    ) -> FormDefinition:
+        """Update an existing form. Raises KeyError if not found."""
+        form = await self._store.get_form(form_id)
+        if form is None:
+            raise KeyError(f"Form not found: {form_id}")
+
+        updates: dict[str, Any] = {"updated_at": datetime.now(timezone.utc)}
+        if name is not None:
+            updates["name"] = name
+        if description is not None:
+            updates["description"] = description
+        if fields is not None:
+            if len(fields) > self._config.max_fields_per_form:
+                raise ValidationError(
+                    f"Too many fields: {len(fields)} > {self._config.max_fields_per_form}"
+                )
+            updates["fields"] = fields
+        if settings is not None:
+            updates["settings"] = settings
+
+        updated = form.model_copy(update=updates)
+        await self._store.save_form(updated)
+        logger.info("Form updated: id=%s", form_id)
+        return updated
+
+    async def publish_form(self, form_id: str) -> FormDefinition:
+        """Publish a form so it accepts submissions. Raises ValueError if no fields."""
+        form = await self._store.get_form(form_id)
+        if form is None:
+            raise KeyError(f"Form not found: {form_id}")
+        if not form.fields:
+            raise ValidationError("Cannot publish a form with no fields.")
+
+        updated = form.model_copy(update={
+            "published": True,
+            "updated_at": datetime.now(timezone.utc),
+        })
+        await self._store.save_form(updated)
+        logger.info("Form published: id=%s", form_id)
+        return updated
+
+    async def submit_form(
+        self,
+        form_id: str,
+        data: dict[str, Any],
+        *,
+        submitted_by: str | None = None,
+        ip_address: str | None = None,
+    ) -> FormSubmission:
+        """Submit a response to a published form.
+
+        Raises KeyError (not found), PermissionError (closed/unpublished), ValueError (invalid).
+        """
+        form = await self._store.get_form(form_id)
+        if form is None:
+            raise KeyError(f"Form not found: {form_id}")
+        if not form.published:
+            raise PermissionError("Form is not published.")
+        if not form.settings.allow_anonymous and submitted_by is None:
+            raise PermissionError("Anonymous submissions are not allowed.")
+
+        # Check close date
+        if form.settings.close_after_date:
+            if datetime.now(timezone.utc) > form.settings.close_after_date:
+                raise PermissionError("Form is closed for submissions.")
+
+        # Check max submissions
+        if form.settings.max_submissions > 0:
+            count = await self._store.count_submissions(form_id)
+            if count >= form.settings.max_submissions:
+                raise PermissionError("Form has reached maximum submissions.")
+
+        # Rate limiting
+        self._check_rate_limit(form_id)
+
+        # Validate
+        errors = self._validator.validate_submission(form, data)
+        if errors:
+            details = "; ".join(f"{e.field}: {e.message}" for e in errors)
+            raise ValidationError(f"Validation failed: {details}")
+
+        submission = FormSubmission(
+            id=str(uuid.uuid4()),
+            form_id=form_id,
+            data=data,
+            submitted_by=submitted_by,
+            ip_address=ip_address,
+        )
+        await self._store.save_submission(submission)
+        logger.info("Submission recorded: id=%s form=%s", submission.id, form_id)
+        return submission
+
+    async def get_submissions(
+        self, form_id: str, *, offset: int = 0, limit: int = 100
+    ) -> list[FormSubmission]:
+        """List submissions for a form with pagination."""
+        return await self._store.get_submissions(form_id, offset=offset, limit=limit)
+
+    async def get_stats(self, form_id: str) -> dict[str, Any]:
+        """Get submission count and last_submission_at. Raises KeyError if not found."""
+        form = await self._store.get_form(form_id)
+        if form is None:
+            raise KeyError(f"Form not found: {form_id}")
+
+        count = await self._store.count_submissions(form_id)
+        last_sub = None
+        if count > 0:
+            subs = await self._store.get_submissions(form_id, offset=0, limit=1)
+            if subs:
+                last_sub = subs[0].submitted_at.isoformat()
+
+        return {
+            "form_id": form_id,
+            "total_submissions": count,
+            "last_submission_at": last_sub,
+            "published": form.published,
+        }
+
+    async def export_submissions(self, form_id: str) -> list[dict[str, Any]]:
+        """Export all submissions as flat dicts (for data-export integration)."""
+        subs = await self._store.get_submissions(form_id, offset=0, limit=100_000)
+        return [
+            {
+                "id": s.id,
+                "submitted_by": s.submitted_by or "anonymous",
+                "submitted_at": s.submitted_at.isoformat(),
+                **s.data,
+            }
+            for s in subs
+        ]
+
+    def _check_rate_limit(self, form_id: str) -> None:
+        """Enforce per-form submission rate limiting."""
+        now = time.monotonic()
+        window = 60.0
+        timestamps = self._rate_limiter[form_id]
+
+        # Prune old entries
+        self._rate_limiter[form_id] = [t for t in timestamps if now - t < window]
+        timestamps = self._rate_limiter[form_id]
+
+        if len(timestamps) >= self._config.rate_limit_per_minute:
+            raise PermissionError("Rate limit exceeded. Try again later.")
+        timestamps.append(now)

forms/store.py

@@ -0,0 +1,142 @@
+"""Form and submission storage backends."""
+
+from __future__ import annotations
+
+import abc
+from typing import Any
+
+from forms.models import FormDefinition, FormSubmission
+
+
+class FormStore(abc.ABC):
+    """Abstract base class for form storage backends."""
+
+    @abc.abstractmethod
+    async def save_form(self, form: FormDefinition) -> FormDefinition:
+        """Persist a form definition (create or update).
+
+        Args:
+            form: The form definition to save.
+
+        Returns:
+            The saved form definition.
+        """
+
+    @abc.abstractmethod
+    async def get_form(self, form_id: str) -> FormDefinition | None:
+        """Retrieve a form definition by ID.
+
+        Args:
+            form_id: The unique form identifier.
+
+        Returns:
+            The form definition, or None if not found.
+        """
+
+    @abc.abstractmethod
+    async def list_forms(
+        self, *, published_only: bool = False, offset: int = 0, limit: int = 100
+    ) -> list[FormDefinition]:
+        """List form definitions with optional filtering.
+
+        Args:
+            published_only: If True, only return published forms.
+            offset: Number of forms to skip.
+            limit: Maximum number of forms to return.
+
+        Returns:
+            List of form definitions.
+        """
+
+    @abc.abstractmethod
+    async def delete_form(self, form_id: str) -> bool:
+        """Delete a form definition and all its submissions.
+
+        Args:
+            form_id: The unique form identifier.
+
+        Returns:
+            True if the form existed and was deleted, False otherwise.
+        """
+
+    @abc.abstractmethod
+    async def save_submission(self, submission: FormSubmission) -> FormSubmission:
+        """Persist a form submission.
+
+        Args:
+            submission: The submission to save.
+
+        Returns:
+            The saved submission.
+        """
+
+    @abc.abstractmethod
+    async def get_submissions(
+        self, form_id: str, *, offset: int = 0, limit: int = 100
+    ) -> list[FormSubmission]:
+        """Retrieve submissions for a form.
+
+        Args:
+            form_id: The form to get submissions for.
+            offset: Number of submissions to skip.
+            limit: Maximum number of submissions to return.
+
+        Returns:
+            List of submissions ordered by submitted_at descending.
+        """
+
+    @abc.abstractmethod
+    async def count_submissions(self, form_id: str) -> int:
+        """Count total submissions for a form.
+
+        Args:
+            form_id: The form to count submissions for.
+
+        Returns:
+            Total number of submissions.
+        """
+
+
+class InMemoryFormStore(FormStore):
+    """Dictionary-backed in-memory form store for development and testing."""
+
+    def __init__(self) -> None:
+        self._forms: dict[str, FormDefinition] = {}
+        self._submissions: dict[str, list[FormSubmission]] = {}
+
+    async def save_form(self, form: FormDefinition) -> FormDefinition:
+        self._forms[form.id] = form
+        return form
+
+    async def get_form(self, form_id: str) -> FormDefinition | None:
+        return self._forms.get(form_id)
+
+    async def list_forms(
+        self, *, published_only: bool = False, offset: int = 0, limit: int = 100
+    ) -> list[FormDefinition]:
+        forms = list(self._forms.values())
+        if published_only:
+            forms = [f for f in forms if f.published]
+        forms.sort(key=lambda f: f.created_at, reverse=True)
+        return forms[offset : offset + limit]
+
+    async def delete_form(self, form_id: str) -> bool:
+        if form_id not in self._forms:
+            return False
+        del self._forms[form_id]
+        self._submissions.pop(form_id, None)
+        return True
+
+    async def save_submission(self, submission: FormSubmission) -> FormSubmission:
+        self._submissions.setdefault(submission.form_id, []).append(submission)
+        return submission
+
+    async def get_submissions(
+        self, form_id: str, *, offset: int = 0, limit: int = 100
+    ) -> list[FormSubmission]:
+        subs = self._submissions.get(form_id, [])
+        sorted_subs = sorted(subs, key=lambda s: s.submitted_at, reverse=True)
+        return sorted_subs[offset : offset + limit]
+
+    async def count_submissions(self, form_id: str) -> int:
+        return len(self._submissions.get(form_id, []))

forms/validator.py

@@ -0,0 +1,235 @@
+"""Form submission validation engine."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from datetime import date, datetime
+from typing import Any
+
+from forms.models import (
+    FieldType,
+    FormDefinition,
+    FormField,
+    ValidationError,
+    ValidationType,
+)
+
+# Type alias for custom validator hooks
+FieldValidator = Callable[[FormField, Any], ValidationError | None]
+
+
+class FormValidator:
+    """Validates form submissions against their form definitions.
+
+    Supports required-field checks, type coercion, built-in validation
+    rules (min/max length, regex patterns, numeric range), and
+    per-field-type custom validator hooks.
+    """
+
+    def __init__(self) -> None:
+        self._custom_validators: dict[FieldType, list[FieldValidator]] = {}
+
+    def register_validator(self, field_type: FieldType, validator: FieldValidator) -> None:
+        """Register a custom validator hook for a specific field type.
+
+        Args:
+            field_type: The field type this validator applies to.
+            validator: Callable(field, value) -> ValidationError | None.
+        """
+        self._custom_validators.setdefault(field_type, []).append(validator)
+
+    def validate_submission(
+        self,
+        form: FormDefinition,
+        data: dict[str, Any],
+    ) -> list[ValidationError]:
+        """Validate submitted data against the form definition.
+
+        Args:
+            form: The form definition to validate against.
+            data: Field-name to value mapping from the submission.
+
+        Returns:
+            List of validation errors. Empty list means valid.
+        """
+        errors: list[ValidationError] = []
+        field_map = {f.name: f for f in form.fields}
+
+        for field in form.fields:
+            value = data.get(field.name)
+            if value is None or (isinstance(value, str) and value.strip() == ""):
+                if field.required:
+                    errors.append(ValidationError(
+                        field=field.name,
+                        message=f"Field '{field.label or field.name}' is required.",
+                        rule_type="required",
+                    ))
+                continue
+
+            coerced, coerce_err = self._coerce_type(field, value)
+            if coerce_err:
+                errors.append(coerce_err)
+                continue
+
+            errors.extend(self._validate_rules(field, coerced))
+            errors.extend(self._run_custom_validators(field, coerced))
+
+        # Warn about unknown fields
+        known = set(field_map.keys())
+        for key in data:
+            if key not in known:
+                errors.append(ValidationError(
+                    field=key,
+                    message=f"Unknown field '{key}'.",
+                    rule_type="unknown_field",
+                ))
+
+        return errors
+
+    def _coerce_type(
+        self, field: FormField, value: Any
+    ) -> tuple[Any, ValidationError | None]:
+        """Attempt to coerce value to the expected type for the field."""
+        try:
+            match field.type:
+                case FieldType.NUMBER:
+                    return self._coerce_number(value), None
+                case FieldType.EMAIL:
+                    return self._coerce_email(field, value)
+                case FieldType.CHECKBOX:
+                    return bool(value), None
+                case FieldType.SELECT:
+                    return self._coerce_select(field, value)
+                case FieldType.MULTISELECT:
+                    return self._coerce_multiselect(field, value)
+                case FieldType.DATE:
+                    return self._coerce_date(value), None
+                case _:
+                    return str(value), None
+        except (ValueError, TypeError) as exc:
+            return None, ValidationError(
+                field=field.name,
+                message=str(exc),
+                rule_type="type",
+            )
+
+    @staticmethod
+    def _coerce_number(value: Any) -> int | float:
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return value
+        return float(value)
+
+    @staticmethod
+    def _coerce_email(
+        field: FormField, value: Any
+    ) -> tuple[str, ValidationError | None]:
+        s = str(value).strip()
+        if "@" not in s or "." not in s.split("@")[-1]:
+            return s, ValidationError(
+                field=field.name,
+                message=f"'{s}' is not a valid email address.",
+                rule_type="type",
+            )
+        return s, None
+
+    @staticmethod
+    def _coerce_select(
+        field: FormField, value: Any
+    ) -> tuple[str, ValidationError | None]:
+        s = str(value)
+        if field.options and s not in field.options:
+            return s, ValidationError(
+                field=field.name,
+                message=f"'{s}' is not a valid option. Choose from: {field.options}.",
+                rule_type="type",
+            )
+        return s, None
+
+    @staticmethod
+    def _coerce_multiselect(
+        field: FormField, value: Any
+    ) -> tuple[list[str], ValidationError | None]:
+        if isinstance(value, str):
+            items = [v.strip() for v in value.split(",")]
+        elif isinstance(value, list):
+            items = [str(v) for v in value]
+        else:
+            items = [str(value)]
+
+        if field.options:
+            invalid = [v for v in items if v not in field.options]
+            if invalid:
+                return items, ValidationError(
+                    field=field.name,
+                    message=f"Invalid options: {invalid}. Choose from: {field.options}.",
+                    rule_type="type",
+                )
+        return items, None
+
+    @staticmethod
+    def _coerce_date(value: Any) -> str:
+        if isinstance(value, (date, datetime)):
+            return value.isoformat()
+        # Validate parseable date string
+        for fmt in ("%Y-%m-%d", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%S%z"):
+            try:
+                datetime.strptime(str(value), fmt)
+                return str(value)
+            except ValueError:
+                continue
+        raise ValueError(f"'{value}' is not a valid date format. Use YYYY-MM-DD.")
+
+    @staticmethod
+    def _validate_rules(field: FormField, value: Any) -> list[ValidationError]:
+        """Apply built-in validation rules to a coerced value."""
+        errors: list[ValidationError] = []
+        for rule in field.validation_rules:
+            match rule.type:
+                case ValidationType.MIN_LENGTH:
+                    if isinstance(value, str) and len(value) < int(rule.value):
+                        errors.append(ValidationError(
+                            field=field.name,
+                            message=rule.message or f"Must be at least {rule.value} characters.",
+                            rule_type=rule.type.value,
+                        ))
+                case ValidationType.MAX_LENGTH:
+                    if isinstance(value, str) and len(value) > int(rule.value):
+                        errors.append(ValidationError(
+                            field=field.name,
+                            message=rule.message or f"Must be at most {rule.value} characters.",
+                            rule_type=rule.type.value,
+                        ))
+                case ValidationType.PATTERN:
+                    if isinstance(value, str) and not re.fullmatch(str(rule.value), value):
+                        errors.append(ValidationError(
+                            field=field.name,
+                            message=rule.message or f"Does not match pattern '{rule.value}'.",
+                            rule_type=rule.type.value,
+                        ))
+                case ValidationType.MIN:
+                    if isinstance(value, (int, float)) and value < float(rule.value):
+                        errors.append(ValidationError(
+                            field=field.name,
+                            message=rule.message or f"Must be at least {rule.value}.",
+                            rule_type=rule.type.value,
+                        ))
+                case ValidationType.MAX:
+                    if isinstance(value, (int, float)) and value > float(rule.value):
+                        errors.append(ValidationError(
+                            field=field.name,
+                            message=rule.message or f"Must be at most {rule.value}.",
+                            rule_type=rule.type.value,
+                        ))
+        return errors
+
+    def _run_custom_validators(
+        self, field: FormField, value: Any
+    ) -> list[ValidationError]:
+        """Run registered custom validators for the field's type."""
+        errors: list[ValidationError] = []
+        for validator in self._custom_validators.get(field.type, []):
+            err = validator(field, value)
+            if err is not None:
+                errors.append(err)
+        return errors

msaas_forms-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+forms/__init__.py,sha256=BjUcJK67rWoAWwH_ZipqeWl2XkblasN6-UEcbC4J2x0,808
+forms/config.py,sha256=GxZNRvnOllSaUq0BjF8M43JJmqOOFHliciJSioF3bro,1960
+forms/models.py,sha256=7h1Uj43quYmk6Y5TVgV1lnKzNkboW8Ahm1nAdbFEbxI,4427
+forms/router.py,sha256=1gmWkLWztimWKCQlwQgdadI9KeK2RGT9xbcUuqdbOSo,5940
+forms/service.py,sha256=cCLiJV07hfeJnnDa6tGASC96-VuOlztSsVpzqgT0djw,8229
+forms/store.py,sha256=AUlQxpMc0T4kr35VP-K7H4mQ9b5Yr6FflGU0iUOF43A,4331
+forms/validator.py,sha256=uD9wNRynUucVndIkjs1VqhLSQs80RUrTwZ6v398inBo,8978
+msaas_forms-0.1.0.dist-info/METADATA,sha256=i8SrHJlLwWGA-x2z_GiCrVCFVzLNBf47QZkApIy6hOw,540
+msaas_forms-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+msaas_forms-0.1.0.dist-info/RECORD,,

msaas_forms-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any