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

vibetuner/services/CLAUDE.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)
+```

vibetuner/services/blob.py

@@ -0,0 +1,175 @@
+"""Blob storage service for file uploads to S3 or R2.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+To extend blob functionality, create wrapper services in the parent services directory.
+"""
+
+import mimetypes
+from pathlib import Path
+from typing import Literal
+
+import aioboto3
+from aiobotocore.config import AioConfig
+
+from vibetuner.config import settings
+from vibetuner.models import BlobModel
+from vibetuner.models.blob import BlobStatus
+
+
+S3_SERVICE_NAME: Literal["s3"] = "s3"
+DEFAULT_CONTENT_TYPE: str = "application/octet-stream"
+
+
+class BlobService:
+    def __init__(
+        self,
+        session: aioboto3.Session | None = None,
+        default_bucket: str | None = None,
+    ) -> None:
+        if (
+            settings.r2_bucket_endpoint_url is None
+            or settings.r2_access_key is None
+            or settings.r2_secret_key is None
+        ):
+            raise ValueError(
+                "R2 bucket endpoint URL, access key, and secret key must be set in settings."
+            )
+        self.session = session or aioboto3.Session(
+            aws_access_key_id=settings.r2_access_key.get_secret_value(),
+            aws_secret_access_key=settings.r2_secret_key.get_secret_value(),
+            region_name=settings.r2_default_region,
+        )
+        self.endpoint_url = str(settings.r2_bucket_endpoint_url)
+        self.config = AioConfig(
+            request_checksum_calculation="when_required",
+            response_checksum_validation="when_required",
+        )
+
+        if not default_bucket:
+            if settings.r2_default_bucket_name is None:
+                raise ValueError(
+                    "Default bucket name must be provided either in settings or as an argument."
+                )
+            self.default_bucket = settings.r2_default_bucket_name
+        else:
+            self.default_bucket = default_bucket
+
+    async def put_object(
+        self,
+        body: bytes,
+        content_type: str = DEFAULT_CONTENT_TYPE,
+        bucket: str | None = None,
+        namespace: str | None = None,
+        original_filename: str | None = None,
+    ) -> BlobModel:
+        """Put an object into the R2 bucket and return the blob model"""
+
+        bucket = bucket or self.default_bucket
+
+        blob = BlobModel.from_bytes(
+            body=body,
+            content_type=content_type,
+            bucket=bucket,
+            namespace=namespace,
+            original_filename=original_filename,
+        )
+
+        await blob.insert()
+
+        if not blob.id:
+            raise ValueError("Blob ID must be set before uploading to R2.")
+
+        try:
+            async with self.session.client(
+                service_name=S3_SERVICE_NAME,
+                endpoint_url=self.endpoint_url,
+                config=self.config,
+            ) as s3_client:
+                await s3_client.put_object(
+                    Bucket=bucket,
+                    Key=blob.full_path,
+                    Body=body,
+                    ContentType=content_type,
+                )
+            blob.status = BlobStatus.UPLOADED
+        except Exception:
+            blob.status = BlobStatus.ERROR
+        finally:
+            await blob.save()
+
+        return blob
+
+    async def put_object_with_extension(
+        self,
+        body: bytes,
+        extension: str,
+        bucket: str | None = None,
+        namespace: str | None = None,
+    ) -> BlobModel:
+        """Put an object into the R2 bucket with content type guessed from extension"""
+        content_type, _ = mimetypes.guess_type(f"file.{extension.lstrip('.')}")
+        content_type = content_type or DEFAULT_CONTENT_TYPE
+
+        return await self.put_object(body, content_type, bucket, namespace)
+
+    async def put_file(
+        self,
+        file_path: Path | str,
+        content_type: str | None = None,
+        bucket: str | None = None,
+        namespace: str | None = None,
+    ) -> BlobModel:
+        """Put a file from filesystem into the R2 bucket"""
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Auto-detect content type if not provided
+        if content_type is None:
+            content_type, _ = mimetypes.guess_type(str(file_path))
+            content_type = content_type or DEFAULT_CONTENT_TYPE
+
+        return await self.put_object(
+            file_path.read_bytes(),
+            content_type,
+            bucket,
+            namespace,
+            original_filename=file_path.name,
+        )
+
+    async def get_object(self, key: str) -> bytes:
+        """Retrieve an object from the R2 bucket"""
+        blob = await BlobModel.get(key)
+        if not blob:
+            raise ValueError(f"Blob not found: {key}")
+
+        async with self.session.client(
+            service_name=S3_SERVICE_NAME,
+            endpoint_url=self.endpoint_url,
+            config=self.config,
+        ) as s3_client:
+            response = await s3_client.get_object(
+                Bucket=blob.bucket,
+                Key=blob.full_path,
+            )
+            return await response["Body"].read()
+
+    async def delete_object(self, key: str) -> None:
+        """Delete an object from the R2 bucket"""
+        blob = await BlobModel.get(key)
+        if not blob:
+            raise ValueError(f"Blob not found: {key}")
+
+        blob.status = BlobStatus.DELETED
+
+        await blob.save()
+
+    async def object_exists(self, key: str, check_bucket: bool = False) -> bool:
+        """Check if an object exists in the R2 bucket"""
+
+        blob = await BlobModel.get(key)
+        if not blob:
+            return False
+
+        return True

vibetuner/services/email.py

@@ -0,0 +1,50 @@
+"""Email service for sending transactional emails via AWS SES.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+To extend email functionality, create wrapper services in the parent services directory.
+"""
+
+from typing import Literal
+
+import boto3
+
+from vibetuner.config import settings
+
+
+SES_SERVICE_NAME: Literal["ses"] = "ses"
+
+
+class SESEmailService:
+    def __init__(
+        self,
+        ses_client=None,
+        from_email: str | None = None,
+    ) -> None:
+        self.ses_client = ses_client or boto3.client(
+            service_name=SES_SERVICE_NAME,
+            region_name=settings.project.aws_default_region,
+            aws_access_key_id=settings.aws_access_key_id.get_secret_value()
+            if settings.aws_access_key_id
+            else None,
+            aws_secret_access_key=settings.aws_secret_access_key.get_secret_value()
+            if settings.aws_secret_access_key
+            else None,
+        )
+        self.from_email = from_email or settings.project.from_email
+
+    async def send_email(
+        self, to_address: str, subject: str, html_body: str, text_body: str
+    ):
+        """Send email using Amazon SES"""
+        response = self.ses_client.send_email(
+            Source=self.from_email,
+            Destination={"ToAddresses": [to_address]},
+            Message={
+                "Subject": {"Data": subject, "Charset": "UTF-8"},
+                "Body": {
+                    "Html": {"Data": html_body, "Charset": "UTF-8"},
+                    "Text": {"Data": text_body, "Charset": "UTF-8"},
+                },
+            },
+        )
+        return response

vibetuner/tasks/AGENTS.md

@@ -0,0 +1,98 @@
+# Core Tasks Module
+
+**IMMUTABLE SCAFFOLDING CODE** - This is the framework's core background task infrastructure.
+
+## What's Here
+
+This module contains the scaffolding's core task components:
+
+- **worker.py** - Streaq worker setup and configuration
+- **context.py** - Task context management (DB, HTTP client, etc.)
+- ****init**.py** - Task infrastructure exports
+
+## Important Rules
+
+⚠️  **DO NOT MODIFY** these core task components directly.
+
+**For changes to core tasks:**
+
+- File an issue at `https://github.com/alltuner/scaffolding`
+- Core changes benefit all projects using the scaffolding
+
+**For your application tasks:**
+
+- Create them in `src/app/tasks/` instead
+- Import the worker from vibetuner: `from vibetuner.tasks.worker import worker`
+
+## Quick Reference
+
+Tasks are only available if job queue was enabled during scaffolding.
+
+The worker is defined in `src/vibetuner/tasks/worker.py` and should be imported from there in your app tasks.
+
+## User Task Pattern (for reference)
+
+Your application tasks in `src/app/tasks/` should follow this pattern:
+
+```python
+# src/app/tasks/emails.py
+from vibetuner.models import UserModel
+from vibetuner.tasks.worker import worker
+
+@worker.task()
+async def send_welcome_email(user_id: str) -> dict[str, str]:
+    """Example background job."""
+
+    # Access context
+    res = await worker.context.http_client.get(url)
+
+    if user := await UserModel.get(user_id):
+        # Perform side effects
+        return {"status": "sent", "user": user.email}
+    return {"status": "skipped"}
+```
+
+## Queueing Tasks
+
+```python
+# In your routes: src/app/frontend/routes/auth.py
+from app.tasks.emails import send_welcome_email
+
+@router.post("/signup")
+async def signup(email: str):
+    user = await create_user(email)
+
+    task = await send_welcome_email.enqueue(user.id)
+    # Optional: await task.result() or check task.id
+
+    return {"status": "registered", "job_id": task.id}
+```
+
+Note: Import your task functions from `src/app/tasks/` but the worker itself comes from `vibetuner.tasks.worker`.
+
+## Worker Management
+
+```bash
+just worker-dev    # Run worker locally with auto-reload
+```
+
+## Task Registration
+
+Add new task modules at the end of `src/app/tasks/__init__.py`:
+
+```python
+# src/app/tasks/__init__.py
+# Import your task modules so decorators register with worker
+from . import emails  # noqa: F401
+from . import new_tasks  # noqa: F401
+```
+
+## Monitoring
+
+```python
+task = await send_digest_email.enqueue(account_id)
+
+status = await task.status()
+result = await task.result(timeout=30)
+await task.abort()  # Cancel if needed
+```

vibetuner/tasks/CLAUDE.md

@@ -0,0 +1,98 @@
+# Core Tasks Module
+
+**IMMUTABLE SCAFFOLDING CODE** - This is the framework's core background task infrastructure.
+
+## What's Here
+
+This module contains the scaffolding's core task components:
+
+- **worker.py** - Streaq worker setup and configuration
+- **context.py** - Task context management (DB, HTTP client, etc.)
+- ****init**.py** - Task infrastructure exports
+
+## Important Rules
+
+⚠️  **DO NOT MODIFY** these core task components directly.
+
+**For changes to core tasks:**
+
+- File an issue at `https://github.com/alltuner/scaffolding`
+- Core changes benefit all projects using the scaffolding
+
+**For your application tasks:**
+
+- Create them in `src/app/tasks/` instead
+- Import the worker from vibetuner: `from vibetuner.tasks.worker import worker`
+
+## Quick Reference
+
+Tasks are only available if job queue was enabled during scaffolding.
+
+The worker is defined in `src/vibetuner/tasks/worker.py` and should be imported from there in your app tasks.
+
+## User Task Pattern (for reference)
+
+Your application tasks in `src/app/tasks/` should follow this pattern:
+
+```python
+# src/app/tasks/emails.py
+from vibetuner.models import UserModel
+from vibetuner.tasks.worker import worker
+
+@worker.task()
+async def send_welcome_email(user_id: str) -> dict[str, str]:
+    """Example background job."""
+
+    # Access context
+    res = await worker.context.http_client.get(url)
+
+    if user := await UserModel.get(user_id):
+        # Perform side effects
+        return {"status": "sent", "user": user.email}
+    return {"status": "skipped"}
+```
+
+## Queueing Tasks
+
+```python
+# In your routes: src/app/frontend/routes/auth.py
+from app.tasks.emails import send_welcome_email
+
+@router.post("/signup")
+async def signup(email: str):
+    user = await create_user(email)
+
+    task = await send_welcome_email.enqueue(user.id)
+    # Optional: await task.result() or check task.id
+
+    return {"status": "registered", "job_id": task.id}
+```
+
+Note: Import your task functions from `src/app/tasks/` but the worker itself comes from `vibetuner.tasks.worker`.
+
+## Worker Management
+
+```bash
+just worker-dev    # Run worker locally with auto-reload
+```
+
+## Task Registration
+
+Add new task modules at the end of `src/app/tasks/__init__.py`:
+
+```python
+# src/app/tasks/__init__.py
+# Import your task modules so decorators register with worker
+from . import emails  # noqa: F401
+from . import new_tasks  # noqa: F401
+```
+
+## Monitoring
+
+```python
+task = await send_digest_email.enqueue(account_id)
+
+status = await task.status()
+result = await task.result(timeout=30)
+await task.abort()  # Cancel if needed
+```

vibetuner/tasks/__init__.py

@@ -0,0 +1,2 @@
+# Import all your tasks here with (noqa: F401)
+# from . import x_tasks

vibetuner/tasks/context.py

@@ -0,0 +1,34 @@
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from httpx import AsyncClient
+from pydantic import BaseModel
+
+from vibetuner.mongo import init_models
+
+
+class Context(BaseModel):
+    http_client: AsyncClient
+    # Add the context properties for your tasks below
+
+    # Until here
+    model_config = {"arbitrary_types_allowed": True}
+
+
+@asynccontextmanager
+async def lifespan() -> AsyncIterator[Context]:
+    await init_models()
+    # Add below anything that should happen before startup
+
+    # Until here
+    async with (
+        AsyncClient() as http_client,
+        # Add any other async context managers you need here
+    ):
+        yield Context(
+            http_client=http_client,
+            # Add any other async context managers you need here
+        )
+
+    # Add below anything that should happen before shutdown
+    # Until here

vibetuner/tasks/worker.py

@@ -0,0 +1,18 @@
+from streaq import Worker
+
+from vibetuner.config import settings
+from vibetuner.tasks.context import lifespan
+
+
+worker = Worker(
+    redis_url=str(settings.project.redis_url),
+    queue_name=(
+        settings.project.project_slug
+        if not settings.debug
+        else f"debug-{settings.project.project_slug}"
+    ),
+    lifespan=lifespan,
+)
+
+# Register tasks
+# use something like from . import task_module_name // noqa: E402, F401

vibetuner/templates/email/AGENTS.md

@@ -0,0 +1,48 @@
+# Core Email Templates - DO NOT MODIFY
+
+**⚠️ IMPORTANT**: Package-managed files. Changes will be lost on package updates.
+
+## How to Override
+
+**NEVER modify files in this directory!** Instead:
+
+1. Copy template to your project's `templates/email/`
+2. Maintain the same directory structure
+3. Your version overrides automatically
+
+### Example
+
+```bash
+# Core template (DO NOT EDIT, bundled in vibetuner package):
+vibetuner/templates/email/default/magic_link.html.jinja
+
+# Your override (CREATE THIS in your project):
+templates/email/default/magic_link.html.jinja
+```
+
+## Template Structure
+
+```text
+vibetuner/email/
+└── default/
+    ├── magic_link.html.jinja  # Passwordless login email (HTML)
+    └── magic_link.txt.jinja   # Passwordless login email (text)
+```
+
+## Magic Link Email
+
+The core provides magic link authentication emails used by the auth system.
+
+### Variables Available
+
+- `login_url` - The magic link URL for authentication
+- `project_name` - Your project's display name
+
+Override these templates to customize branding, styling, and content.
+
+## Best Practices
+
+1. Always provide both HTML and text versions
+2. Test overrides after scaffolding updates
+3. Keep branding consistent across all emails
+4. Use inline styles for HTML emails

vibetuner/templates/email/CLAUDE.md

@@ -0,0 +1,48 @@
+# Core Email Templates - DO NOT MODIFY
+
+**⚠️ IMPORTANT**: Package-managed files. Changes will be lost on package updates.
+
+## How to Override
+
+**NEVER modify files in this directory!** Instead:
+
+1. Copy template to your project's `templates/email/`
+2. Maintain the same directory structure
+3. Your version overrides automatically
+
+### Example
+
+```bash
+# Core template (DO NOT EDIT, bundled in vibetuner package):
+vibetuner/templates/email/default/magic_link.html.jinja
+
+# Your override (CREATE THIS in your project):
+templates/email/default/magic_link.html.jinja
+```
+
+## Template Structure
+
+```text
+vibetuner/email/
+└── default/
+    ├── magic_link.html.jinja  # Passwordless login email (HTML)
+    └── magic_link.txt.jinja   # Passwordless login email (text)
+```
+
+## Magic Link Email
+
+The core provides magic link authentication emails used by the auth system.
+
+### Variables Available
+
+- `login_url` - The magic link URL for authentication
+- `project_name` - Your project's display name
+
+Override these templates to customize branding, styling, and content.
+
+## Best Practices
+
+1. Always provide both HTML and text versions
+2. Test overrides after scaffolding updates
+3. Keep branding consistent across all emails
+4. Use inline styles for HTML emails

vibetuner/templates/email/default/magic_link.html.jinja

@@ -0,0 +1,16 @@
+<html>
+    <body>
+        <h2>Sign in to {{ project_name }}</h2>
+        <p>Click the link below to sign in to your account:</p>
+        <p>
+            <a href="{{ login_url }}"
+               style="background-color: #007bff;
+                      color: white;
+                      padding: 12px 24px;
+                      text-decoration: none;
+                      border-radius: 4px">Sign In</a>
+        </p>
+        <p>This link will expire in 15 minutes.</p>
+        <p>If you didn't request this, you can safely ignore this email.</p>
+    </body>
+</html>