vibetuner 2.6.1__py3-none-any.whl → 2.7.0__py3-none-any.whl

vibetuner/models/blob.py

@@ -0,0 +1,89 @@
+"""Blob storage model for file uploads and management.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Manages file metadata for S3 or local storage backends.
+"""
+
+import hashlib
+from enum import StrEnum
+from typing import Self
+
+from beanie import Document
+from pydantic import Field
+
+from vibetuner.models.registry import register_model
+
+from .mixins import TimeStampMixin
+
+
+class BlobStatus(StrEnum):
+    PENDING = "pending"
+    UPLOADED = "uploaded"
+    DELETED = "deleted"
+    ERROR = "error"
+
+
+@register_model
+class BlobModel(Document, TimeStampMixin):
+    status: BlobStatus = Field(
+        default=BlobStatus.PENDING,
+        description="Status of the blob indicating if it is pending, uploaded, or deleted",
+    )
+    bucket: str = Field(
+        ...,
+        description="Storage bucket name where the object is stored",
+    )
+    content_type: str = Field(
+        ...,
+        description="MIME type of the object (e.g., image/png, application/pdf)",
+    )
+    original_filename: str | None = Field(
+        default=None,
+        description="Original name of the file as uploaded by the user (if applicable)",
+    )
+    namespace: str | None = Field(
+        default=None,
+        description="Namespaces (prefixes) for the object, used for organization (optional)",
+    )
+    checksum: str = Field(
+        ...,
+        description="SHA256 hash of the object for integrity verification",
+    )
+    size: int = Field(..., description="Size of the object in bytes")
+
+    @property
+    def full_path(self) -> str:
+        """Get the full path of the blob in the bucket."""
+        if self.namespace:
+            return f"{self.namespace}/{self.id}"
+        else:
+            return f"{self.id}"
+
+    @classmethod
+    def from_bytes(
+        cls,
+        body: bytes,
+        content_type: str,
+        bucket: str,
+        namespace: str | None = None,
+        original_filename: str | None = None,
+    ) -> Self:
+        """Create a BlobModel instance from raw bytes and metadata."""
+        return cls(
+            original_filename=original_filename,
+            content_type=content_type,
+            bucket=bucket,
+            namespace=namespace,
+            checksum=cls.calculate_checksum(body),
+            size=len(body),
+        )
+
+    @staticmethod
+    def calculate_checksum(body: bytes) -> str:
+        """Calculate SHA256 checksum of the given bytes."""
+
+        return hashlib.sha256(body).hexdigest()
+
+    class Settings:
+        name = "blobs"
+        keep_nulls = False

vibetuner/models/email_verification.py

@@ -0,0 +1,84 @@
+"""Email verification model for magic link authentication.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Handles passwordless authentication via email verification tokens.
+"""
+
+import secrets
+from datetime import datetime, timedelta
+from typing import Optional, Self
+
+from beanie import Document
+from beanie.operators import Eq, Set
+from pydantic import Field
+
+from vibetuner.models.registry import register_model
+from vibetuner.time import now
+
+
+# Email verification token model
+@register_model
+class EmailVerificationTokenModel(Document):
+    email: str = Field(
+        ...,
+        description="Email address requesting verification",
+    )
+    token: str = Field(
+        ...,
+        description="Secure random token for email verification",
+    )
+    expires_at: datetime = Field(
+        ...,
+        description="Token expiration timestamp",
+    )
+    used: bool = Field(
+        default=False,
+        description="Whether the token has been consumed",
+    )
+
+    class Settings:
+        name = "email_verification_tokens"
+        indexes = [
+            [("token", 1)],
+            [("email", 1)],
+            [("expires_at", 1)],
+        ]
+
+    @classmethod
+    async def create_token(cls, email: str, expires_minutes: int = 15) -> Self:
+        """Create a new verification token for email login"""
+        token = secrets.token_urlsafe(32)
+        expires_at = now() + timedelta(minutes=expires_minutes)
+
+        # Invalidate any existing tokens for this email
+        await cls.find(Eq(cls.email, email)).update_many(Set({cls.used: True}))
+
+        verification_token = cls(
+            email=email, token=token, expires_at=expires_at, used=False
+        )
+
+        return await verification_token.insert()
+
+    @classmethod
+    async def verify_token(cls, token: str) -> Optional[Self]:
+        """Verify and consume a token"""
+        verification_token: Optional[Self] = await cls.find_one(
+            Eq(cls.token, token), Eq(cls.used, False)
+        )
+
+        if not verification_token:
+            return None
+
+        # Ensure expires_at is timezone-aware for comparison
+        expires_at = verification_token.expires_at
+        if expires_at.tzinfo is None:
+            from datetime import timezone
+
+            expires_at = expires_at.replace(tzinfo=timezone.utc)
+
+        if expires_at < now():
+            return None
+
+        # Mark token as used
+        verification_token.used = True
+        return await verification_token.save()

vibetuner/models/mixins.py

@@ -0,0 +1,76 @@
+"""Reusable model mixins for common functionality.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Provides timestamp tracking and other common model behaviors.
+"""
+
+from datetime import datetime, timedelta
+from enum import StrEnum
+from typing import Self
+
+from beanie import Insert, Replace, Save, SaveChanges, Update, before_event
+from pydantic import BaseModel, Field
+
+from vibetuner.time import Unit, now
+
+
+class Since(StrEnum):
+    """Reference moment for age calculations."""
+
+    CREATION = "creation"
+    UPDATE = "update"
+
+
+# ────────────────────────────────────────────────────────────────
+#  Drop-in mixin
+# ────────────────────────────────────────────────────────────────
+class TimeStampMixin(BaseModel):
+    """
+    ✦ Automatic UTC timestamps on insert/update
+    ✦ Typed helpers for age checks
+
+        doc.age()                       → timedelta
+        doc.age_in(Unit.HOURS)          → float
+        doc.is_older_than(td, since=…)  → bool
+    """
+
+    db_insert_dt: datetime = Field(
+        default_factory=lambda: now(),
+        description="Timestamp when the document was first created and inserted into the database (UTC)",
+    )
+    db_update_dt: datetime = Field(
+        default_factory=lambda: now(),
+        description="Timestamp when the document was last modified or updated (UTC)",
+    )
+
+    # ── Beanie hooks ────────────────────────────────────────────
+    @before_event(Insert)
+    def _touch_on_insert(self) -> None:
+        _now = now()
+        self.db_insert_dt = _now
+        self.db_update_dt = _now
+
+    @before_event(Update, SaveChanges, Save, Replace)
+    def _touch_on_update(self) -> None:
+        self.db_update_dt = now()
+
+    # ── Public helpers ──────────────────────────────────────────
+    def age(self, *, since: Since = Since.CREATION) -> timedelta:
+        """Timedelta since *creation* or last *update* (default: creation)."""
+        ref = self.db_update_dt if since is Since.UPDATE else self.db_insert_dt
+        return now() - ref
+
+    def age_in(
+        self, unit: Unit = Unit.SECONDS, *, since: Since = Since.CREATION
+    ) -> float:
+        """Age expressed as a float in the requested `unit`."""
+        return self.age(since=since).total_seconds() / unit.factor
+
+    def is_older_than(self, delta: timedelta, *, since: Since = Since.CREATION) -> bool:
+        """True iff the document’s age ≥ `delta`."""
+        return self.age(since=since) >= delta
+
+    def touch(self) -> Self:
+        """Manually bump `db_update_dt` and return `self` (chain-friendly)."""
+        self.db_update_dt = now()
+        return self

vibetuner/models/oauth.py

@@ -0,0 +1,57 @@
+from typing import Self
+
+from beanie import Document
+from beanie.operators import Eq
+from pydantic import BaseModel, Field
+
+from vibetuner.models.registry import register_model
+
+from .mixins import TimeStampMixin
+
+
+class OauthProviderModel(BaseModel):
+    identifier: str
+    params: dict[str, str] = {}
+    client_kwargs: dict[str, str]
+    config: dict[str, str]
+
+
+@register_model
+class OAuthAccountModel(Document, TimeStampMixin):
+    provider: str = Field(
+        ...,
+        description="OAuth provider name (google, github, twitter, etc.)",
+    )
+    provider_user_id: str = Field(
+        ...,
+        description="Unique user identifier from the OAuth provider",
+    )
+    email: str | None = Field(
+        default=None,
+        description="Email address retrieved from OAuth provider profile",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Full display name retrieved from OAuth provider profile",
+    )
+    picture: str | None = Field(
+        default=None,
+        description="Profile picture URL retrieved from OAuth provider",
+    )
+
+    class Settings:
+        name = "oauth_accounts"
+        indexes = [
+            [("provider", 1), ("provider_user_id", 1)],
+        ]
+
+    @classmethod
+    async def get_by_provider_and_id(
+        cls,
+        provider: str,
+        provider_user_id: str,
+    ) -> Self | None:
+        return await cls.find_one(
+            Eq(cls.provider, provider),
+            Eq(cls.provider_user_id, provider_user_id),
+        )

vibetuner/models/registry.py

@@ -0,0 +1,15 @@
+from beanie import Document, View
+
+
+_MODEL_REGISTRY: list[type[Document] | type[View]] = []
+
+
+def register_model(cls):
+    """Decorator to register a model"""
+    _MODEL_REGISTRY.append(cls)
+    return cls
+
+
+def get_all_models():
+    """Get all registered models (call at startup)"""
+    return _MODEL_REGISTRY

vibetuner/models/types.py

@@ -0,0 +1,16 @@
+"""Common type definitions for models.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Provides type aliases and re-exports for consistent typing across models.
+"""
+
+from typing import TYPE_CHECKING, TypeAlias, TypeVar
+
+from beanie import Document, Link as BeanieLink
+
+
+if TYPE_CHECKING:
+    _T = TypeVar("_T", bound=Document)
+    Link: TypeAlias = _T
+else:
+    Link = BeanieLink

vibetuner/models/user.py

@@ -0,0 +1,91 @@
+"""Core user model for authentication and user management.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Extend functionality by creating custom models that reference or extend these models.
+"""
+
+from functools import cached_property
+from typing import Any, List, Self
+
+from beanie import Document
+from beanie.operators import Eq
+from pydantic import BaseModel, Field
+from pydantic_extra_types.language_code import LanguageAlpha2
+
+from vibetuner.models.registry import register_model
+
+from .mixins import TimeStampMixin
+from .oauth import OAuthAccountModel
+from .types import Link
+
+
+class UserSettings(BaseModel):
+    """User settings for the application.
+
+    This class holds the default settings for the user, such as language and theme.
+    It can be extended to include more user-specific settings in the future.
+    """
+
+    language: LanguageAlpha2 | None = Field(
+        default=None,
+        description="Preferred language for the user",
+    )
+
+    @cached_property
+    def session_dict(self) -> dict[str, Any]:
+        """Return a dictionary representation of the user settings for session storage.
+
+        Make sure to only include fields that are necessary for the session.
+        """
+        return self.model_dump(
+            exclude_none=True,
+            exclude_unset=True,
+            include={
+                "language",
+            },
+        )
+
+
+@register_model
+class UserModel(Document, TimeStampMixin):
+    email: str | None = Field(
+        default=None,
+        description="Primary email address for authentication",
+    )
+    name: str | None = Field(
+        default=None,
+        description="User's full display name",
+    )
+    picture: str | None = Field(
+        default=None,
+        description="URL to user's profile picture or avatar",
+    )
+    oauth_accounts: List[Link[OAuthAccountModel]] = Field(
+        default_factory=list,
+        description="Connected OAuth provider accounts (Google, GitHub, etc.)",
+    )
+
+    user_settings: UserSettings = Field(
+        default_factory=UserSettings,
+        description="User-specific settings for the application",
+    )
+
+    class Settings:
+        name = "users"
+        keep_nulls = False
+
+    @cached_property
+    def session_dict(self) -> dict[str, Any]:
+        return {
+            "id": str(self.id),
+            **self.model_dump(
+                exclude_none=True,
+                exclude_unset=True,
+                include={"name", "email", "picture"},
+            ),
+            "settings": self.user_settings.session_dict,
+        }
+
+    @classmethod
+    async def get_by_email(cls, email: str) -> Self | None:
+        return await cls.find_one(Eq(cls.email, email))

vibetuner/mongo.py

@@ -0,0 +1,18 @@
+from beanie import init_beanie
+from pymongo import AsyncMongoClient
+
+from vibetuner.config import settings
+from vibetuner.models.registry import get_all_models
+
+
+async def init_models() -> None:
+    """Initialize MongoDB connection and register all Beanie models."""
+
+    client: AsyncMongoClient = AsyncMongoClient(
+        host=str(settings.project.mongodb_url),
+        compressors=["zstd"],
+    )
+
+    await init_beanie(
+        database=client[settings.mongo_dbname], document_models=get_all_models()
+    )

vibetuner/paths.py

@@ -0,0 +1,112 @@
+from importlib.resources import files
+from pathlib import Path
+
+# Package-relative paths (for bundled templates in the vibetuner package)
+_package_files = files("vibetuner")
+_package_templates_traversable = _package_files / "templates"
+
+# Convert to Path when actually used (handles both filesystem and zip-based packages)
+def _get_package_templates_path() -> Path:
+    """Get package templates path, works for both installed and editable installs."""
+    # For most cases, we can convert directly to Path
+    # For zip files, importlib.resources handles extraction automatically
+    try:
+        return Path(str(_package_templates_traversable))
+    except (TypeError, ValueError):
+        # If we can't convert to Path, we're in a zip or similar
+        # In this case, we'll need to use as_file() context manager when accessing
+        # For now, raise an error - we can enhance this later if needed
+        raise RuntimeError(
+            "Package templates are in a non-filesystem location. "
+            "This is not yet supported."
+        )
+
+
+package_templates = _get_package_templates_path()
+
+# Project root (set at runtime by the application using vibetuner)
+# When None, only package templates are available
+root: Path | None = None
+fallback_path = "defaults"
+
+
+def set_project_root(project_root: Path) -> None:
+    """Set the project root directory for the application using vibetuner.
+
+    This enables access to project-specific templates, assets, and locales.
+    Must be called before accessing project-specific paths.
+    """
+    global root, templates, app_templates, locales, config_vars
+    global assets, statics, css, js, favicons, img
+    global frontend_templates, email_templates, markdown_templates
+
+    root = project_root
+
+    # Update project-specific paths
+    templates = root / "templates"
+    app_templates = templates  # Deprecated: projects now use templates/ directly
+    locales = root / "locales"
+    config_vars = root / ".copier-answers.yml"
+
+    # Update asset paths
+    assets = root / "assets"
+    statics = assets / "statics"
+    css = statics / "css"
+    js = statics / "js"
+    favicons = statics / "favicons"
+    img = statics / "img"
+
+    # Update template lists to include project overrides
+    frontend_templates = [templates / "frontend", package_templates / "frontend"]
+    email_templates = [templates / "email", package_templates / "email"]
+    markdown_templates = [templates / "markdown", package_templates / "markdown"]
+
+
+def to_template_path_list(path: Path) -> list[Path]:
+    return [
+        path,
+        path / fallback_path,
+    ]
+
+
+def fallback_static_default(static_type: str, file_name: str) -> Path:
+    """Return a fallback path for a file."""
+    if root is None:
+        raise RuntimeError(
+            "Project root not set. Call set_project_root() before accessing assets."
+        )
+
+    paths_to_check = [
+        statics / static_type / file_name,
+        statics / fallback_path / static_type / file_name,
+    ]
+
+    for path in paths_to_check:
+        if path.exists():
+            return path
+
+    raise FileNotFoundError(
+        f"Could not find {file_name} in any of the fallback paths: {paths_to_check}"
+    )
+
+
+# Core templates point to package (always available)
+core_templates = package_templates
+
+# Template paths - initially only package templates, updated when set_project_root() is called
+frontend_templates = [package_templates / "frontend"]
+email_templates = [package_templates / "email"]
+markdown_templates = [package_templates / "markdown"]
+
+# Project-specific paths - will be None until set_project_root() is called
+# These get updated by set_project_root()
+templates: Path | None = None
+app_templates: Path | None = None
+locales: Path | None = None
+config_vars: Path | None = None
+assets: Path | None = None
+statics: Path | None = None
+css: Path | None = None
+js: Path | None = None
+favicons: Path | None = None
+img: Path | None = None

vibetuner/services/AGENTS.md

@@ -0,0 +1,104 @@
+# Core Services Module
+
+**IMMUTABLE SCAFFOLDING CODE** - These are the framework's core services that provide essential functionality.
+
+## What's Here
+
+This module contains the scaffolding's core services:
+
+- **email.py** - Email sending via AWS SES
+- **blob.py** - File storage and blob management
+
+## Important Rules
+
+⚠️  **DO NOT MODIFY** these core services directly.
+
+**For changes to core services:**
+
+- File an issue at `https://github.com/alltuner/scaffolding`
+- Core changes benefit all projects using the scaffolding
+
+**For your application services:**
+
+- Create them in `src/app/services/` instead
+- Import core services when needed: `from vibetuner.services.email import send_email`
+
+## User Service Pattern (for reference)
+
+Your application services in `src/app/services/` should follow this pattern:
+
+```python
+from vibetuner.models import UserModel
+
+class NotificationService:
+    async def send_notification(
+        self,
+        user: UserModel,
+        message: str,
+        priority: str = "normal"
+    ) -> bool:
+        # Implementation
+        return True
+
+# Singleton
+notification_service = NotificationService()
+```
+
+## Using Core Services
+
+### Email Service
+
+```python
+from vibetuner.services.email import send_email
+
+await send_email(
+    to_email="user@example.com",
+    subject="Welcome",
+    html_content="<h1>Welcome!</h1>",
+    text_content="Welcome!"
+)
+```
+
+### Blob Service
+
+```python
+from vibetuner.services.blob import blob_service
+
+# Upload file
+blob = await blob_service.upload(file_data, "image.png")
+
+# Get file URL
+url = await blob_service.get_url(blob.id)
+```
+
+## Creating Your Own Services
+
+Place your application services in `src/app/services/`:
+
+```python
+# src/app/services/external_api.py
+import httpx
+
+async def call_api(api_url: str, api_key: str, data: dict) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            api_url,
+            json=data,
+            headers={"Authorization": f"Bearer {api_key}"}
+        )
+        response.raise_for_status()
+        return response.json()
+```
+
+## Dependency Injection
+
+```python
+from fastapi import Depends
+
+@router.post("/notify")
+async def notify(
+    message: str,
+    service=Depends(lambda: notification_service)
+):
+    await service.send_notification(user, message)
+```