epok-toolkit 1.12.8__py3-none-any.whl

epok_toolkit/apps.py

@@ -0,0 +1,14 @@
+from django.apps import AppConfig
+from django.conf import settings
+
+class EpokToolkitConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'epok_toolkit'
+
+    def ready(self):
+        # Importar tus settings por defecto
+        from . import default_settings
+
+        for setting in dir(default_settings):
+            if setting.isupper() and not hasattr(settings, setting):
+                setattr(settings, setting, getattr(default_settings, setting))

epok_toolkit/default_settings.py

@@ -0,0 +1,33 @@
+# Configuración de correo electrónico
+EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
+EMAIL_HOST = 'smtp.gmail.com'
+EMAIL_PORT = 465
+EMAIL_USE_SSL = True
+EMAIL_USE_TLS = False
+EMAIL_DEFAULT_FROM_EMAIL = "no-reply@epok.ai"
+EMAIL_HOST_USER = "no-reply@epok.ai"
+EMAIL_HOST_PASSWORD = "your-email-password"
+
+
+# Configuración de whatsApp
+API_KEY = "your-whatsapp-api-key"
+INSTANCE = "instance-id"
+SERVER_URL = "https://your-server-url.com/"
+
+
+
+#  ---------- TEMPLATE DE CORREO ELECTRÓNICO ---------- #
+TEMPLATES_SETTINGS = {
+    "company": {
+        "name": "Congrats",
+        "email": "info@compania.com",
+        "eslogan": "Eslogan sin definir",
+        "footer": "¡Nos vemos pronto!<br><em> El equipo de Congrats 🥳</em>"
+    },
+    "colors": {
+        "background": "#f9fafb",
+        "primary": "#4f46e5",
+        "text": "#374151",
+        "white": "#ffffff"
+    }
+}

epok_toolkit/django/__init__.py

@@ -0,0 +1,6 @@
+from .cache import *
+from .fields import *
+from .manager import *
+from .models import *
+from .response import *
+from .viewsets import *

epok_toolkit/django/cache.py

@@ -0,0 +1,130 @@
+# utils/cacher.py
+from rest_framework import viewsets
+from rest_framework_extensions.cache.mixins import CacheResponseMixin
+from rest_framework_extensions.cache.decorators import cache_response
+from django.views.decorators.cache import cache_page
+from colorstreak import Logger as log
+from functools import wraps
+from django.utils.decorators import method_decorator
+# --- clave por usuario + params + página ----------------------
+from rest_framework_extensions.key_constructor.constructors import DefaultKeyConstructor
+from rest_framework_extensions.key_constructor.bits import UserKeyBit, QueryParamsKeyBit, PaginationKeyBit
+
+
+"""
+cacher.py — utilidades de caché centralizadas
+============================================
+
+Este módulo agrupa, en un solo lugar, las dos capas de caché que aplicamos en
+nuestra API DRF:
+
+    📦  cache_get   → capa de *serialización*  (drf extensions @cache_response)
+    🚀  cache_full  → capa de *vista completa* (Django @cache_page)
+
+Para no repetir la misma lógica en cada vista, exportamos:
+
+    •  `CachedViewSet`  ->  incluye CacheResponseMixin listo para usar.
+    •  Decoradores      ->  `cache_get`,  `cache_full`.
+    •  `TimeToLive`     ->  constantes de segundos ligadas a colores/emoji.
+
+Leyenda TTL (la misma del CSV)
+------------------------------
+    🔴  1 min   (60 s)      | cambios frecuentes
+    🟡  2 --> 5 min (~300 s)     | lecturas comunes
+    🟢  10 --> 30 min (~1800 s)  | datos casi estáticos
+
+Emojis ↔ capas
+--------------
+    🗄️   consultas ORM   (cacheops / get_or_set)
+    📦   serialización   (cache_response)
+    🚀   vista completa  (cache_page)
+    🌐   CDN / navegador (Cache‑Control)
+
+"""
+
+
+
+class TimeToLive:
+    """
+    Constantes de TTL ligadas a la paleta del CSV:
+
+        🔴 RED    | 1 min  (60 s)
+        🟡 YELLOW | 5 min  (300 s)
+        🟢 GREEN  | 30 min (1800 s)
+    """
+    RED    = 60          # 1 minuto
+    YELLOW = 60 * 5      # 5 minutos
+    GREEN  = 60 * 30     # 30 minutos
+
+
+class UserQueryKey(DefaultKeyConstructor):
+    user = UserKeyBit()
+    query_params = QueryParamsKeyBit()
+    pagination = PaginationKeyBit()
+
+_DEFAULT_KEY  = UserQueryKey().get_key
+_DEFAULT_TTL  = TimeToLive.RED
+
+
+
+class CachedViewSet(CacheResponseMixin, viewsets.ModelViewSet):
+    """
+    Herédame si vas a usar cache_get o cache_full.
+    Nada más que eso; no impone TTL.
+    """
+    pass
+
+
+
+
+def cache_get(ttl=_DEFAULT_TTL, key_func=_DEFAULT_KEY):
+    """
+    Capa: Serialización 📦
+    Devuelve un decorador que cachea la serialización DRF *una sola vez*,
+    evitando envolver la vista nuevamente en cada petición.
+
+    Ejemplo:
+        @cache_get(ttl=TimeToLive.RED)
+        def view(...): ...
+    """
+    def decorator(view_fn):
+        # Pre‑construimos la función cacheada UNA vez
+        cached_fn = cache_response(ttl, key_func=key_func)(view_fn)
+
+        @wraps(view_fn)
+        def wrapped(*args, **kwargs):
+            log.library(
+                f"[📦 cache_get] {view_fn.__qualname__} | ttl={ttl}s"
+            )
+            # Llamamos directamente a la versión ya decorada,
+            # para no crear cadenas de closures ni excepciones duplicadas.
+            return cached_fn(*args, **kwargs)
+
+        return wrapped
+
+    return decorator
+
+
+def cache_full(ttl=_DEFAULT_TTL, key_prefix=""):
+    """
+    Capa: Respuesta HTTP 🚀
+    Devuelve un decorador que cachea la vista completa vía cache_page
+    *al momento de ejecutar la vista*.
+
+    Ejemplo:
+        @cache_full(ttl=TimeToLive.GREEN, key_prefix="ticket_pdf")
+        def view(...): ...
+    """
+    def decorator(view_fn):
+        # Adapt the function-level cache_page decorator to a bound‑method
+        page_deco = cache_page(ttl, key_prefix=key_prefix)
+        decorated_fn = method_decorator(page_deco)(view_fn)
+
+        @wraps(view_fn)
+        def wrapped(self, request, *args, **kwargs):
+            log.library(f"[🚀 cache_full] {view_fn.__qualname__} | ttl={ttl}s | prefix={key_prefix}")
+            return decorated_fn(self, request, *args, **kwargs)
+
+        return wrapped
+
+    return decorator

epok_toolkit/django/fields.py

@@ -0,0 +1,30 @@
+from django.db import models
+from decimal import Decimal
+
+class StandarFloatField(models.FloatField):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('default', 0.0)
+        super().__init__(*args, **kwargs)
+
+class StandarDecimalField(models.DecimalField):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('max_digits', 10)
+        kwargs.setdefault('decimal_places', 2)
+        kwargs.setdefault('default', Decimal('0.00'))
+        super().__init__(*args, **kwargs)
+
+class StandarIntegerField(models.IntegerField):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('default', 0)
+        super().__init__(*args, **kwargs)
+
+class StandarCharField(models.CharField):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('max_length', 20)
+        kwargs.setdefault('default', 'Not specified')
+        super().__init__(*args, **kwargs)
+        
+class StandarDateTimeField(models.DateTimeField):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('auto_now_add', True)
+        super().__init__(*args, **kwargs)

epok_toolkit/django/manager.py

@@ -0,0 +1,38 @@
+from django.db import models
+
+class OptimizedQuerySet(models.QuerySet):
+    def optimized(self, select_fields=None, prefetch_fields=None):
+        qs = self
+        if select_fields:
+            qs = qs.select_related(*select_fields)
+        if prefetch_fields:
+            qs = qs.prefetch_related(*prefetch_fields)
+        return qs
+
+
+class OptimizedManager(models.Manager):
+    """
+    Custom manager for optimized querysets.
+    """
+    def __init__(self, select_fields_full=None, prefetch_fields_full=None, select_fields_simple=None, prefetch_fields_simple=None, *args, **kwargs):
+
+        super().__init__(*args, **kwargs)
+        self._select_fields_full = select_fields_full or []
+        self._prefetch_fields_full = prefetch_fields_full   or []
+        self._select_fields_simple = select_fields_simple or []
+        self._prefetch_fields_simple = prefetch_fields_simple or []
+
+    def get_queryset(self):
+        return OptimizedQuerySet(self.model, using=self._db)
+
+    def full(self):
+        return self.get_queryset().optimized(
+            select_fields=self._select_fields_full,
+            prefetch_fields=self._prefetch_fields_full
+        )
+
+    def simple(self):
+        return self.get_queryset().optimized(
+            select_fields=self._select_fields_simple,
+            prefetch_fields=self._prefetch_fields_simple
+        )

epok_toolkit/django/models.py

@@ -0,0 +1,42 @@
+from uuid import uuid4
+from django.conf import settings
+from django.db import models
+
+
+
+class UUID4Mixin(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid4, editable=False)
+
+    class Meta:
+        abstract = True
+        
+
+
+class TimeStampMixin(models.Model):
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        
+
+
+class SoftDeleteMixin(models.Model):
+    is_deleted = models.BooleanField(default=False)
+
+    class Meta:
+        abstract = True
+        indexes = [
+            models.Index(fields=['is_deleted']),
+        ]
+
+
+
+class CreatorsMixin(models.Model):
+    created_by = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, 
+                                  on_delete=models.CASCADE, related_name='%(class)s_created')
+    updated_by = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, 
+                                  on_delete=models.CASCADE, related_name='%(class)s_updated')
+
+    class Meta:
+        abstract = True

epok_toolkit/django/response.py

@@ -0,0 +1,57 @@
+from rest_framework.response import Response
+from django.http import HttpResponse
+from typing import Optional
+
+
+STATUS_MESSAGES = {
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    204: "No Content",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    500: "Internal Server Error",
+}
+
+
+
+def response(data: Optional[dict] = None, status_code: int = 200, message: Optional[str] = None) -> Response:
+    success = True if 200 <= status_code < 300 else False
+
+    if status_code not in STATUS_MESSAGES:
+        raise ValueError(f"Invalid status code: {status_code}. Must be one of {list(STATUS_MESSAGES.keys())}.")
+    
+    if status_code == 201 and not data:
+        raise ValueError("Data cannot be empty for status code 201 (Created).")
+    
+    if status_code == 204 and data is not None:
+        raise ValueError("Data must be None for status code 204 (No Content).")
+    
+    if not message:
+        message = STATUS_MESSAGES[status_code]
+
+    if not data:
+        data = {}
+    
+    payload = {
+        "status": success,
+        "message": message
+    }
+    if success and data is not None:
+        payload["data"] = data
+    elif not success:
+        payload["error"] = data
+    return Response(payload, status=status_code)
+
+
+
+def file_response(file: bytes, filename: str, content_type: str = "application/octet-stream", status_code: int = 200) -> HttpResponse:
+    """
+    Returns a file response with the given file content, filename, and content type.
+    """
+    response = HttpResponse(file, status=status_code)
+    response["Content-Disposition"] = f'attachment; filename="{filename}"'
+    response["Content-Type"] = content_type
+    return response

epok_toolkit/django/utils/__init__.py

@@ -0,0 +1 @@
+from .magic_link import *

epok_toolkit/django/utils/magic_link.py

@@ -0,0 +1,27 @@
+from datetime import timedelta
+import jwt
+from django.utils import timezone
+from django.conf import settings
+
+def generate_login_magic_token(user, minutes_valid=10):
+    """
+    Genera un token JWT válido por X minutos para login sin contraseña.
+    Incluye un propósito específico para distinguirlo de otros tipos de token.
+    """
+    payload = {
+        "user_id": str(user.id),
+        "exp": timezone.now() + timedelta(minutes=minutes_valid),
+        "purpose": "magic_login",
+    }
+
+    token = jwt.encode(payload, settings.SECRET_KEY, algorithm="HS256")
+    if isinstance(token, bytes):
+        token = token.decode("utf-8")
+    return token
+
+def build_login_magic_link(token):
+    """
+    Construye el enlace completo hacia tu frontend.
+    Ajusta la ruta a donde quieras que el frontend reciba el token.
+    """
+    return f"{settings.FRONTEND_URL}#/magic-login?token={token}"

epok_toolkit/django/viewsets.py

@@ -0,0 +1,98 @@
+# core/viewsets.py
+from rest_framework import viewsets
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.permissions import IsAuthenticated
+from colorstreak import Logger as log
+
+class DefaultPagination(PageNumberPagination):
+    """
+    Clase de paginación por defecto para los ViewSets.
+    Puedes personalizarla según tus necesidades.
+    """
+    page_size = 10
+    page_size_query_param = 'page_size'
+    max_page_size = 100
+
+
+
+class BaseOptimizedViewSet(viewsets.ModelViewSet):
+    """
+    Clase base para ViewSets optimizados.
+    
+    """
+    queryset = None
+    write_serializer_class = None
+    update_serializer_class = None
+    simple_serializer_class = None
+    full_serializer_class = None
+    serializer_class = None
+    extensions_auto_optimize = True
+
+    permission_classes = [IsAuthenticated]
+
+    pagination_class = DefaultPagination
+
+    filterset_fields = []
+    search_fields = []
+    ordering_fields = []
+    ordering = []
+
+    def get_queryset(self):
+        # aqui heredamos de la libreria estandar
+        qs = super().get_queryset()
+        model_cls = qs.model
+        manager = model_cls._default_manager
+
+        if hasattr(manager, 'simple') and self.action == 'list':
+            #log.library("| LIBRERIA | Usando QS simple")
+            qs = manager.simple()
+        elif hasattr(manager, 'full'):
+            #log.library("| LIBRERIA | Usando QS full")
+            qs = manager.full()
+
+        try:
+            #log.library("| LIBRERIA | Filtrando por created_by")
+            qs_created_by= qs.filter(created_by=self.request.user)
+            return qs_created_by
+        except Exception as e:
+            log.error(f"| LIBRERIA | Error al filtrar por created_by: {e}")
+            log.info("| LIBRERIA | Filtrado sin created_by")
+            return qs
+
+
+
+    def get_serializer_class(self):
+        
+        match self.action:
+            case 'create' if self.write_serializer_class is not None:
+                return self.write_serializer_class
+            case 'update' | 'partial_update' if self.update_serializer_class is not None and self.write_serializer_class is not None:
+                return self.update_serializer_class
+            case 'list' if self.simple_serializer_class is not None:
+                return self.simple_serializer_class
+            case 'retrieve' if self.full_serializer_class is not None:
+                return self.full_serializer_class
+            case _ if self.serializer_class is not None:
+                # log.warning(f"| LIBRERIA | No se encontró serializer específico para la acción '{self.action}', usando el por defecto.")
+                return self.serializer_class
+            case _:
+                log.error("| LIBRERIA | No se encontró serializer por defecto")
+                raise ValueError("No se encontró serializer por defecto")
+
+    def perform_create(self, serializer):
+        try:
+            #log.library("| LIBRERIA |Guardando con created_by y updated_by")
+            serializer.save(created_by=self.request.user, updated_by=self.request.user)
+        except Exception as e:
+            log.error(f"| LIBRERIA | Error al guardar: {e}")
+            log.info("| LIBRERIA | Guardando sin created_by y updated_by")
+            serializer.save()
+
+    def perform_update(self, serializer):
+        try:
+            #log.library("| LIBRERIA | Guardando con updated_by")
+            serializer.save(updated_by=self.request.user)
+        except Exception as e:
+            log.error(f"| LIBRERIA | Error al actualizar: {e}")
+            log.info("| LIBRERIA | Guardando sin updated_by")
+            serializer.save()

epok_toolkit/email/__init__.py

@@ -0,0 +1 @@
+from .email_async import send_email

epok_toolkit/email/email_async.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import logging
+import smtplib
+from celery import shared_task, states
+from celery.exceptions import Ignore
+from .engine import EmailEngine
+
+log = logging.getLogger(__name__)
+
+@shared_task(
+    bind=True,
+    autoretry_for=(smtplib.SMTPException, ConnectionError, TimeoutError),
+    retry_backoff=True,       # 2, 4, 8, 16… s
+    retry_jitter=True,        # +- aleatorio
+    max_retries=3,
+    ignore_result=True,       # <-- ¡importante!
+)
+def send_email_async(self, template_key, context, recipient, attachments=None):
+    try:
+        engine = EmailEngine()
+        engine.send(
+            template_key=template_key,
+            context=context,
+            recipient=recipient,
+            attachments=attachments,
+        )
+        # No retornamos nada; evitamos que Celery/Redis serialice blobs.
+    except smtplib.SMTPSenderRefused as exc:
+        # 552 => el servidor rechaza tamaño. No vale la pena reintentar.
+        if exc.smtp_code == 552:
+            log.error("SMTP 552 – tamaño excedido; abortando reintentos: %s", exc)
+            # Marcamos la tarea como FAILURE, pero NO reintentamos.
+            self.update_state(state=states.FAILURE, meta=str(exc))
+            raise Ignore()    # Detiene la cadena Celery sin más
+        # Otros códigos (550, 451, etc.) siguen flujo normal de retry
+        raise
+
+def send_email(template_key, context, recipient, attachments=None):
+    send_email_async.delay(template_key, context, recipient, attachments) # type: ignore

epok_toolkit/email/engine.py

@@ -0,0 +1,69 @@
+"""
+notifications/method/email_engine.py
+Motor de envío de correos basado en plantillas del catálogo TEMPLATES.
+La vista sólo indica qué plantilla usar, el contexto y el destinatario.
+"""
+
+from typing import Dict
+from django.core.mail import send_mail
+from django.conf import settings
+
+from .templates import TEMPLATES, EmailTemplate, RenderedEmail
+
+
+class EmailEngine:
+    """
+    Ejemplo de uso:
+
+        engine = EmailEngine()
+        engine.send(
+            template_key="password_reset",
+            context={"name": "Fer", "reset_link": "https://app.congrats.mx/#/reset/abc"},
+            recipient="fer@example.com",
+        )
+    """
+
+    def __init__(self, templates: Dict[str, EmailTemplate] = TEMPLATES, backend=send_mail):
+        self.templates = templates
+        self.backend = backend
+
+    # --------------------------------------------------------------------- #
+    # API pública
+    # --------------------------------------------------------------------- #
+    def send(
+        self,
+        template_key: "str", # TODO: PONER CLASE VALIDADOR DE TEMPLATE EVITAR INYECCION 
+        context: Dict[str, str],
+        recipient: str,
+        attachments: Dict[str, bytes] | None = None,
+    ) -> None:
+        """
+        Envía un correo usando la plantilla indicada.
+        - `context` debe contener todas las llaves declaradas en `required_vars`.
+        - `attachments` puede ser un dict {filename: bytes} para adjuntar PDFs u otros ficheros.
+        """
+        # Verificar plantilla
+        if template_key not in self.templates:
+            raise KeyError(f"Plantilla '{template_key}' no existe en TEMPLATES.") # TODO: PONER CUALES SI SON VALIDAS
+
+        # Renderizar cuerpo
+        rendered: RenderedEmail = self.templates[template_key].render(context)
+
+        # Crear e‑mail multipart (texto + HTML)
+        from django.core.mail import EmailMultiAlternatives
+
+        message = EmailMultiAlternatives(
+            subject=rendered.subject,
+            body=rendered.plain,
+            from_email=settings.EMAIL_HOST_USER,
+            to=[recipient],
+        )
+        message.attach_alternative(rendered.html, "text/html")
+
+        # Adjuntos opcionales
+        if attachments:
+            for name, data in attachments.items():
+                message.attach(name, data, "application/pdf")
+
+        # Enviar
+        message.send(fail_silently=False)