msaas-waitlist 0.1.0__tar.gz

msaas_waitlist-0.1.0/.gitignore

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

msaas_waitlist-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-waitlist
+Version: 0.1.0
+Summary: Waitlist and early access management for SaaS launches
+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.110.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'

msaas_waitlist-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "msaas-waitlist"
+version = "0.1.0"
+description = "Waitlist and early access management for SaaS launches"
+requires-python = ">=3.12"
+dependencies = [
+"msaas-api-core",
+"msaas-errors","pydantic>=2.0"
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "httpx>=0.27", "fastapi>=0.110.0", "ruff>=0.8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waitlist"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_waitlist-0.1.0/src/waitlist/__init__.py

@@ -0,0 +1,65 @@
+"""Waitlist -- early access and waitlist management for SaaS launches."""
+
+from waitlist.config import get_waitlist, init_waitlist, reset
+from waitlist.models import (
+    BatchApproveRequest,
+    EntryFilter,
+    EntryStatus,
+    JoinRequest,
+    PositionResponse,
+    WaitlistConfig,
+    WaitlistEntry,
+    WaitlistInvite,
+    WaitlistStats,
+)
+from waitlist.notifications import (
+    LoggingNotificationHandler,
+    NoopNotificationHandler,
+    NotificationHandler,
+)
+from waitlist.router import create_waitlist_router
+from waitlist.service import (
+    CapacityReachedError,
+    DuplicateEntryError,
+    EntryNotFoundError,
+    InvalidStateError,
+    InviteError,
+    WaitlistError,
+    WaitlistService,
+)
+from waitlist.store import InMemoryStore, WaitlistStore
+
+__all__ = [
+    # Config
+    "get_waitlist",
+    "init_waitlist",
+    "reset",
+    # Models
+    "BatchApproveRequest",
+    "EntryFilter",
+    "EntryStatus",
+    "JoinRequest",
+    "PositionResponse",
+    "WaitlistConfig",
+    "WaitlistEntry",
+    "WaitlistInvite",
+    "WaitlistStats",
+    # Service
+    "WaitlistService",
+    # Errors
+    "CapacityReachedError",
+    "DuplicateEntryError",
+    "EntryNotFoundError",
+    "InvalidStateError",
+    "InviteError",
+    "WaitlistError",
+    # Store
+    "InMemoryStore",
+    "WaitlistStore",
+    # Notifications
+    "LoggingNotificationHandler",
+    "NoopNotificationHandler",
+    "NotificationHandler",
+    # Router
+    "create_waitlist_router",
+]

msaas_waitlist-0.1.0/src/waitlist/config.py

@@ -0,0 +1,64 @@
+"""Global waitlist configuration and service singleton."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from waitlist.models import WaitlistConfig
+
+if TYPE_CHECKING:
+    from waitlist.service import WaitlistService
+
+_service: WaitlistService | None = None
+_config: WaitlistConfig | None = None
+
+
+def init_waitlist(config: WaitlistConfig | None = None) -> WaitlistConfig:
+    """Initialise the waitlist module with the given (or default) config.
+
+    This stores the config globally so that ``get_waitlist()`` can build
+    the service lazily.
+    """
+    global _config, _service
+    _config = config or WaitlistConfig()
+    _service = None  # reset so next get_waitlist() rebuilds
+    return _config
+
+
+def get_config() -> WaitlistConfig:
+    """Return the current config, raising if ``init_waitlist`` was never called."""
+    if _config is None:
+        raise RuntimeError("Waitlist not initialised. Call init_waitlist() first.")
+    return _config
+
+
+def get_waitlist() -> WaitlistService:
+    """Return the global WaitlistService singleton.
+
+    Creates one on first call using the stored config and the default
+    InMemoryStore + LoggingNotificationHandler.
+    """
+    global _service
+    if _service is not None:
+        return _service
+
+    cfg = get_config()
+
+    # Lazy imports to avoid circular dependencies
+    from waitlist.notifications import LoggingNotificationHandler
+    from waitlist.service import WaitlistService
+    from waitlist.store import InMemoryStore
+
+    _service = WaitlistService(
+        store=InMemoryStore(),
+        config=cfg,
+        notification_handler=LoggingNotificationHandler(),
+    )
+    return _service
+
+
+def reset() -> None:
+    """Reset global state -- useful in tests."""
+    global _service, _config
+    _service = None
+    _config = None

msaas_waitlist-0.1.0/src/waitlist/models.py

@@ -0,0 +1,131 @@
+"""Waitlist domain models built on Pydantic v2."""
+
+from __future__ import annotations
+
+import secrets
+from datetime import UTC, datetime
+from enum import StrEnum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class EntryStatus(StrEnum):
+    """Lifecycle states for a waitlist entry."""
+
+    WAITING = "waiting"
+    APPROVED = "approved"
+    INVITED = "invited"
+    JOINED = "joined"
+    REJECTED = "rejected"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+class WaitlistConfig(BaseModel):
+    """Settings that control waitlist behaviour."""
+
+    auto_approve: bool = Field(default=False, description="Automatically approve new entries")
+    max_capacity: int | None = Field(
+        default=None, description="Maximum number of entries (None = unlimited)"
+    )
+    require_email_verification: bool = Field(
+        default=False, description="Require email verification before approval"
+    )
+    priority_fields: list[str] = Field(
+        default_factory=list,
+        description="Metadata keys that increase priority score",
+    )
+    invite_expiry_hours: int = Field(default=72, description="Hours before an invite token expires")
+
+
+# ---------------------------------------------------------------------------
+# Core domain objects
+# ---------------------------------------------------------------------------
+
+
+class WaitlistEntry(BaseModel):
+    """A single person on the waitlist."""
+
+    id: UUID = Field(default_factory=uuid4)
+    email: str
+    name: str = ""
+    status: EntryStatus = EntryStatus.WAITING
+    position: int = 0
+    priority_score: float = 0.0
+    metadata: dict[str, str | int | float | bool] = Field(default_factory=dict)
+    referral_code: str | None = None
+    referred_by: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    approved_at: datetime | None = None
+    invited_at: datetime | None = None
+
+
+class WaitlistInvite(BaseModel):
+    """An invitation token linked to an approved entry."""
+
+    id: UUID = Field(default_factory=uuid4)
+    entry_id: UUID
+    token: str = Field(default_factory=lambda: secrets.token_urlsafe(32))
+    expires_at: datetime
+    accepted_at: datetime | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        return datetime.now(UTC) > self.expires_at
+
+    @property
+    def is_accepted(self) -> bool:
+        return self.accepted_at is not None
+
+
+class WaitlistStats(BaseModel):
+    """Aggregate statistics for the waitlist."""
+
+    total_entries: int = 0
+    waiting: int = 0
+    approved: int = 0
+    invited: int = 0
+    joined: int = 0
+    rejected: int = 0
+    avg_wait_time_hours: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# API request / response helpers
+# ---------------------------------------------------------------------------
+
+
+class JoinRequest(BaseModel):
+    """Payload for joining the waitlist."""
+
+    email: str
+    name: str = ""
+    metadata: dict[str, str | int | float | bool] = Field(default_factory=dict)
+    referral_code: str | None = None
+
+
+class BatchApproveRequest(BaseModel):
+    """Payload for batch-approving entries."""
+
+    count: int = Field(ge=1, le=1000)
+
+
+class EntryFilter(BaseModel):
+    """Query parameters for listing entries."""
+
+    status: EntryStatus | None = None
+    limit: int = Field(default=50, ge=1, le=500)
+    offset: int = Field(default=0, ge=0)
+
+
+class PositionResponse(BaseModel):
+    """Position information returned to a waitlist user."""
+
+    entry_id: UUID
+    position: int
+    total_ahead: int
+    status: EntryStatus

msaas_waitlist-0.1.0/src/waitlist/notifications.py

@@ -0,0 +1,63 @@
+"""Notification handlers for waitlist lifecycle events."""
+
+from __future__ import annotations
+
+import logging
+from typing import Protocol, runtime_checkable
+
+from waitlist.models import WaitlistEntry, WaitlistInvite
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class NotificationHandler(Protocol):
+    """Protocol that any notification backend must satisfy."""
+
+    async def send_waitlist_confirmation(self, entry: WaitlistEntry) -> None: ...
+    async def send_approval(self, entry: WaitlistEntry) -> None: ...
+    async def send_invite(self, entry: WaitlistEntry, invite: WaitlistInvite) -> None: ...
+    async def send_rejection(self, entry: WaitlistEntry) -> None: ...
+
+
+class LoggingNotificationHandler:
+    """Default handler that simply logs events -- no external I/O."""
+
+    async def send_waitlist_confirmation(self, entry: WaitlistEntry) -> None:
+        logger.info(
+            "Waitlist confirmation for %s (%s) at position %d",
+            entry.email,
+            entry.id,
+            entry.position,
+        )
+
+    async def send_approval(self, entry: WaitlistEntry) -> None:
+        logger.info("Approval notification for %s (%s)", entry.email, entry.id)
+
+    async def send_invite(self, entry: WaitlistEntry, invite: WaitlistInvite) -> None:
+        logger.info(
+            "Invite sent to %s (%s), token=%s, expires=%s",
+            entry.email,
+            entry.id,
+            invite.token,
+            invite.expires_at.isoformat(),
+        )
+
+    async def send_rejection(self, entry: WaitlistEntry) -> None:
+        logger.info("Rejection notification for %s (%s)", entry.email, entry.id)
+
+
+class NoopNotificationHandler:
+    """Handler that does nothing -- useful when notifications are disabled."""
+
+    async def send_waitlist_confirmation(self, entry: WaitlistEntry) -> None:
+        pass
+
+    async def send_approval(self, entry: WaitlistEntry) -> None:
+        pass
+
+    async def send_invite(self, entry: WaitlistEntry, invite: WaitlistInvite) -> None:
+        pass
+
+    async def send_rejection(self, entry: WaitlistEntry) -> None:
+        pass

msaas_waitlist-0.1.0/src/waitlist/router.py

@@ -0,0 +1,141 @@
+"""FastAPI router for waitlist HTTP endpoints."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from errors import (
+    ConflictError,
+    NotFoundError,
+    ValidationError,
+)
+from fastapi import APIRouter, status
+
+from waitlist.models import (
+    BatchApproveRequest,
+    EntryFilter,
+    EntryStatus,
+    JoinRequest,
+    PositionResponse,
+    WaitlistEntry,
+    WaitlistInvite,
+    WaitlistStats,
+)
+from waitlist.service import (
+    CapacityReachedError,
+    DuplicateEntryError,
+    EntryNotFoundError,
+    InvalidStateError,
+    InviteError,
+    WaitlistService,
+)
+
+
+def create_waitlist_router(service: WaitlistService | None = None) -> APIRouter:
+    """Build and return a FastAPI APIRouter wired to the given service.
+
+    If *service* is ``None``, falls back to the global singleton via
+    ``get_waitlist()``.
+    """
+    router = APIRouter(prefix="/waitlist", tags=["waitlist"])
+
+    def _svc() -> WaitlistService:
+        if service is not None:
+            return service
+        from waitlist.config import get_waitlist
+
+        return get_waitlist()
+
+    # ------------------------------------------------------------------
+    # Join
+    # ------------------------------------------------------------------
+
+    @router.post("/join", response_model=WaitlistEntry, status_code=status.HTTP_201_CREATED)
+    async def join_waitlist(body: JoinRequest) -> WaitlistEntry:
+        try:
+            return await _svc().join(
+                email=body.email,
+                name=body.name,
+                metadata=body.metadata,
+                referral_code=body.referral_code,
+            )
+        except DuplicateEntryError as exc:
+            raise ConflictError(str(exc)) from exc
+        except CapacityReachedError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    # ------------------------------------------------------------------
+    # Position
+    # ------------------------------------------------------------------
+
+    @router.get("/position/{entry_id}", response_model=PositionResponse)
+    async def get_position(entry_id: UUID) -> PositionResponse:
+        try:
+            return await _svc().get_position(entry_id)
+        except EntryNotFoundError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    # ------------------------------------------------------------------
+    # Moderation
+    # ------------------------------------------------------------------
+
+    @router.post("/approve/{entry_id}", response_model=WaitlistEntry)
+    async def approve_entry(entry_id: UUID) -> WaitlistEntry:
+        try:
+            return await _svc().approve(entry_id)
+        except EntryNotFoundError as exc:
+            raise NotFoundError(str(exc)) from exc
+        except InvalidStateError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.post("/reject/{entry_id}", response_model=WaitlistEntry)
+    async def reject_entry(entry_id: UUID) -> WaitlistEntry:
+        try:
+            return await _svc().reject(entry_id)
+        except EntryNotFoundError as exc:
+            raise NotFoundError(str(exc)) from exc
+        except InvalidStateError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.post("/approve-batch", response_model=list[WaitlistEntry])
+    async def approve_batch(body: BatchApproveRequest) -> list[WaitlistEntry]:
+        return await _svc().approve_batch(body.count)
+
+    # ------------------------------------------------------------------
+    # Invitations
+    # ------------------------------------------------------------------
+
+    @router.post("/invite/{entry_id}", response_model=WaitlistInvite)
+    async def invite_entry(entry_id: UUID) -> WaitlistInvite:
+        try:
+            return await _svc().invite(entry_id)
+        except EntryNotFoundError as exc:
+            raise NotFoundError(str(exc)) from exc
+        except InvalidStateError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    @router.post("/accept/{token}", response_model=WaitlistEntry)
+    async def accept_invite(token: str) -> WaitlistEntry:
+        try:
+            return await _svc().accept_invite(token)
+        except InviteError as exc:
+            raise ValidationError(str(exc)) from exc
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    @router.get("/stats", response_model=WaitlistStats)
+    async def get_stats() -> WaitlistStats:
+        return await _svc().get_stats()
+
+    @router.get("/entries", response_model=list[WaitlistEntry])
+    async def list_entries(
+        status_filter: EntryStatus | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[WaitlistEntry]:
+        filt = EntryFilter(status=status_filter, limit=limit, offset=offset)
+        return await _svc().list_entries(filt)
+
+    return router