kroxy 0.1.0__py3-none-any.whl

kroxy/discord/giveaway.py

@@ -0,0 +1,226 @@
+"""
+kroxy.discord.giveaway - Full-featured Discord giveaway system.
+"""
+
+import asyncio
+import random
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Callable, Set, Any
+
+
+@dataclass
+class GiveawayEntry:
+    user_id: int
+    entries: int = 1
+    joined_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class Giveaway:
+    """Represents a single giveaway."""
+
+    prize: str
+    host_id: int
+    channel_id: int
+    guild_id: int
+    winner_count: int = 1
+    ends_at: float = 0.0
+    giveaway_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8].upper())
+    message_id: Optional[int] = None
+    required_role_id: Optional[int] = None
+    bonus_roles: Dict[int, int] = field(default_factory=dict)
+    entries: Dict[int, GiveawayEntry] = field(default_factory=dict)
+    ended: bool = False
+    winners: List[int] = field(default_factory=list)
+
+    def add_entry(self, user_id: int, role_ids: List[int] = None) -> int:
+        """Add or update an entry. Returns total entries for this user."""
+        bonus = 0
+        if role_ids and self.bonus_roles:
+            bonus = sum(
+                self.bonus_roles[r] for r in role_ids if r in self.bonus_roles
+            )
+        total = 1 + bonus
+
+        if user_id in self.entries:
+            self.entries[user_id].entries = total
+        else:
+            self.entries[user_id] = GiveawayEntry(user_id=user_id, entries=total)
+        return total
+
+    def remove_entry(self, user_id: int) -> bool:
+        """Remove a user's entry. Returns True if removed."""
+        if user_id in self.entries:
+            del self.entries[user_id]
+            return True
+        return False
+
+    def pick_winners(self) -> List[int]:
+        """Pick weighted random winners."""
+        if not self.entries:
+            return []
+
+        pool: List[int] = []
+        for user_id, entry in self.entries.items():
+            pool.extend([user_id] * entry.entries)
+
+        count = min(self.winner_count, len(self.entries))
+        winners: List[int] = []
+        while len(winners) < count and pool:
+            picked = random.choice(pool)
+            winners.append(picked)
+            pool = [u for u in pool if u != picked]
+
+        self.winners = winners
+        self.ended = True
+        return winners
+
+    def reroll(self, exclude: List[int] = None) -> List[int]:
+        """Reroll winners, optionally excluding previous winners."""
+        exclude = exclude or self.winners
+        eligible = {uid: e for uid, e in self.entries.items() if uid not in exclude}
+        if not eligible:
+            return []
+
+        pool: List[int] = []
+        for user_id, entry in eligible.items():
+            pool.extend([user_id] * entry.entries)
+
+        count = min(self.winner_count, len(eligible))
+        winners: List[int] = []
+        while len(winners) < count and pool:
+            picked = random.choice(pool)
+            winners.append(picked)
+            pool = [u for u in pool if u != picked]
+
+        self.winners = winners
+        return winners
+
+    @property
+    def total_entries(self) -> int:
+        return sum(e.entries for e in self.entries.values())
+
+    @property
+    def participant_count(self) -> int:
+        return len(self.entries)
+
+    @property
+    def time_remaining(self) -> float:
+        return max(0.0, self.ends_at - time.time())
+
+    @property
+    def is_active(self) -> bool:
+        return not self.ended and self.time_remaining > 0
+
+    def to_dict(self) -> Dict:
+        return {
+            "giveaway_id": self.giveaway_id,
+            "prize": self.prize,
+            "host_id": self.host_id,
+            "channel_id": self.channel_id,
+            "guild_id": self.guild_id,
+            "winner_count": self.winner_count,
+            "ends_at": self.ends_at,
+            "message_id": self.message_id,
+            "required_role_id": self.required_role_id,
+            "bonus_roles": self.bonus_roles,
+            "entries": {str(k): {"user_id": v.user_id, "entries": v.entries}
+                        for k, v in self.entries.items()},
+            "ended": self.ended,
+            "winners": self.winners,
+        }
+
+
+class GiveawayManager:
+    """
+    Manages multiple giveaways with automatic scheduling.
+
+    Usage:
+        manager = GiveawayManager()
+        manager.on_end = my_end_callback
+        g = await manager.create(prize="Nitro", host_id=..., channel_id=...,
+                                  guild_id=..., duration=3600)
+    """
+
+    def __init__(self):
+        self._giveaways: Dict[str, Giveaway] = {}
+        self.on_end: Optional[Callable] = None
+        self._tasks: Dict[str, asyncio.Task] = {}
+
+    def get(self, giveaway_id: str) -> Optional[Giveaway]:
+        return self._giveaways.get(giveaway_id)
+
+    def get_by_message(self, message_id: int) -> Optional[Giveaway]:
+        for g in self._giveaways.values():
+            if g.message_id == message_id:
+                return g
+        return None
+
+    def all_active(self) -> List[Giveaway]:
+        return [g for g in self._giveaways.values() if g.is_active]
+
+    def all_ended(self) -> List[Giveaway]:
+        return [g for g in self._giveaways.values() if g.ended]
+
+    async def create(
+        self,
+        prize: str,
+        host_id: int,
+        channel_id: int,
+        guild_id: int,
+        duration: int,
+        winner_count: int = 1,
+        required_role_id: int = None,
+        bonus_roles: Dict[int, int] = None,
+    ) -> Giveaway:
+        """Create and schedule a giveaway. duration is in seconds."""
+        g = Giveaway(
+            prize=prize,
+            host_id=host_id,
+            channel_id=channel_id,
+            guild_id=guild_id,
+            winner_count=winner_count,
+            ends_at=time.time() + duration,
+            required_role_id=required_role_id,
+            bonus_roles=bonus_roles or {},
+        )
+        self._giveaways[g.giveaway_id] = g
+        self._tasks[g.giveaway_id] = asyncio.create_task(
+            self._schedule_end(g, duration)
+        )
+        return g
+
+    async def end_now(self, giveaway_id: str) -> Optional[Giveaway]:
+        """Force-end a giveaway immediately."""
+        g = self._giveaways.get(giveaway_id)
+        if g and not g.ended:
+            task = self._tasks.pop(giveaway_id, None)
+            if task:
+                task.cancel()
+            await self._finish(g)
+        return g
+
+    async def cancel(self, giveaway_id: str) -> bool:
+        """Cancel a giveaway without picking winners."""
+        g = self._giveaways.pop(giveaway_id, None)
+        if g:
+            task = self._tasks.pop(giveaway_id, None)
+            if task:
+                task.cancel()
+            g.ended = True
+            return True
+        return False
+
+    async def _schedule_end(self, giveaway: Giveaway, delay: int):
+        await asyncio.sleep(delay)
+        await self._finish(giveaway)
+
+    async def _finish(self, giveaway: Giveaway):
+        winners = giveaway.pick_winners()
+        if self.on_end:
+            try:
+                await self.on_end(giveaway=giveaway, winners=winners)
+            except Exception:
+                pass

kroxy/discord/music.py

@@ -0,0 +1,236 @@
+"""
+kroxy.discord.music - Discord music bot utilities and queue management.
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any, Callable
+from enum import Enum
+
+
+class LoopMode(Enum):
+    NONE = "none"
+    TRACK = "track"
+    QUEUE = "queue"
+
+
+@dataclass
+class Track:
+    """Represents a music track."""
+    title: str
+    url: str
+    stream_url: str
+    duration: int
+    requester_id: int
+    thumbnail: Optional[str] = None
+    source: str = "unknown"
+
+    @property
+    def duration_str(self) -> str:
+        mins, secs = divmod(self.duration, 60)
+        hours, mins = divmod(mins, 60)
+        if hours:
+            return f"{hours}:{mins:02d}:{secs:02d}"
+        return f"{mins}:{secs:02d}"
+
+    def to_dict(self) -> Dict:
+        return {
+            "title": self.title,
+            "url": self.url,
+            "duration": self.duration,
+            "requester_id": self.requester_id,
+            "thumbnail": self.thumbnail,
+            "source": self.source,
+        }
+
+
+class MusicQueue:
+    """Thread-safe music queue."""
+
+    def __init__(self):
+        self._queue: List[Track] = []
+
+    def add(self, track: Track):
+        self._queue.append(track)
+
+    def add_next(self, track: Track):
+        """Insert a track at the front of the queue."""
+        self._queue.insert(0, track)
+
+    def pop(self) -> Optional[Track]:
+        return self._queue.pop(0) if self._queue else None
+
+    def peek(self) -> Optional[Track]:
+        return self._queue[0] if self._queue else None
+
+    def remove(self, index: int) -> Optional[Track]:
+        if 0 <= index < len(self._queue):
+            return self._queue.pop(index)
+        return None
+
+    def move(self, from_index: int, to_index: int) -> bool:
+        if not (0 <= from_index < len(self._queue)):
+            return False
+        track = self._queue.pop(from_index)
+        to_index = min(to_index, len(self._queue))
+        self._queue.insert(to_index, track)
+        return True
+
+    def shuffle(self):
+        import random
+        random.shuffle(self._queue)
+
+    def clear(self):
+        self._queue.clear()
+
+    def __len__(self) -> int:
+        return len(self._queue)
+
+    def __iter__(self):
+        return iter(self._queue)
+
+    @property
+    def is_empty(self) -> bool:
+        return len(self._queue) == 0
+
+    @property
+    def total_duration(self) -> int:
+        return sum(t.duration for t in self._queue)
+
+
+class MusicPlayer:
+    """
+    Guild-scoped music player state manager.
+
+    Wire this to your actual voice client (discord.py / nextcord / etc.).
+    The player tracks state; actual audio playback is done via your voice client.
+    """
+
+    def __init__(self, guild_id: int, channel_id: int = None, text_channel_id: int = None):
+        self.guild_id = guild_id
+        self.channel_id = channel_id
+        self.text_channel_id = text_channel_id
+        self.queue = MusicQueue()
+        self.current: Optional[Track] = None
+        self.loop_mode: LoopMode = LoopMode.NONE
+        self.volume: float = 1.0
+        self.paused: bool = False
+        self.started_at: Optional[float] = None
+        self.paused_at: Optional[float] = None
+        self._pause_duration: float = 0.0
+
+        self.on_track_start: Optional[Callable] = None
+        self.on_track_end: Optional[Callable] = None
+        self.on_queue_empty: Optional[Callable] = None
+
+    @property
+    def position(self) -> float:
+        """Current playback position in seconds."""
+        if self.started_at is None:
+            return 0.0
+        if self.paused and self.paused_at:
+            return self.paused_at - self.started_at - self._pause_duration
+        return time.time() - self.started_at - self._pause_duration
+
+    def set_volume(self, volume: float) -> float:
+        """Set volume 0.0 – 2.0. Returns clamped value."""
+        self.volume = max(0.0, min(2.0, volume))
+        return self.volume
+
+    def set_loop(self, mode: str) -> LoopMode:
+        """Set loop mode: 'none', 'track', or 'queue'."""
+        self.loop_mode = LoopMode(mode.lower())
+        return self.loop_mode
+
+    def toggle_pause(self) -> bool:
+        """Toggle pause state. Returns new paused state."""
+        if self.paused:
+            self._pause_duration += time.time() - (self.paused_at or time.time())
+            self.paused_at = None
+            self.paused = False
+        else:
+            self.paused_at = time.time()
+            self.paused = True
+        return self.paused
+
+    async def play_next(self) -> Optional[Track]:
+        """Advance to the next track based on loop mode."""
+        if self.loop_mode == LoopMode.TRACK and self.current:
+            next_track = self.current
+        elif self.loop_mode == LoopMode.QUEUE and self.current:
+            self.queue.add(self.current)
+            next_track = self.queue.pop()
+        else:
+            next_track = self.queue.pop()
+
+        if next_track is None:
+            self.current = None
+            self.started_at = None
+            if self.on_queue_empty:
+                await self.on_queue_empty(guild_id=self.guild_id)
+            return None
+
+        self.current = next_track
+        self.started_at = time.time()
+        self.paused = False
+        self._pause_duration = 0.0
+
+        if self.on_track_start:
+            await self.on_track_start(track=next_track, player=self)
+        return next_track
+
+    async def skip(self) -> Optional[Track]:
+        """Skip the current track."""
+        if self.on_track_end and self.current:
+            await self.on_track_end(track=self.current, player=self)
+        old_loop = self.loop_mode
+        self.loop_mode = LoopMode.NONE
+        next_track = await self.play_next()
+        self.loop_mode = old_loop
+        return next_track
+
+    def stop(self):
+        """Stop playback and clear queue."""
+        self.current = None
+        self.queue.clear()
+        self.started_at = None
+        self.paused = False
+
+    def get_state(self) -> Dict:
+        """Return a snapshot of the player state."""
+        return {
+            "guild_id": self.guild_id,
+            "channel_id": self.channel_id,
+            "current": self.current.to_dict() if self.current else None,
+            "queue_length": len(self.queue),
+            "queue_duration": self.queue.total_duration,
+            "loop_mode": self.loop_mode.value,
+            "volume": self.volume,
+            "paused": self.paused,
+            "position": round(self.position, 1),
+        }
+
+
+class MusicPlayerManager:
+    """Manages one MusicPlayer per guild."""
+
+    def __init__(self):
+        self._players: Dict[int, MusicPlayer] = {}
+
+    def get(self, guild_id: int) -> Optional[MusicPlayer]:
+        return self._players.get(guild_id)
+
+    def get_or_create(self, guild_id: int, channel_id: int = None,
+                      text_channel_id: int = None) -> MusicPlayer:
+        if guild_id not in self._players:
+            self._players[guild_id] = MusicPlayer(guild_id, channel_id, text_channel_id)
+        return self._players[guild_id]
+
+    def remove(self, guild_id: int):
+        player = self._players.pop(guild_id, None)
+        if player:
+            player.stop()
+
+    def all_players(self) -> List[MusicPlayer]:
+        return list(self._players.values())

kroxy/discord/utils.py

@@ -0,0 +1,190 @@
+"""
+kroxy.discord.utils - General Discord utility functions.
+"""
+
+import re
+import time
+import datetime
+from typing import Optional, Union
+
+
+class Utils:
+    """Collection of Discord utility helpers."""
+
+    # ── Embed builder ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def build_embed(
+        title: str = None,
+        description: str = None,
+        color: int = 0x5865F2,
+        fields: list = None,
+        footer: str = None,
+        thumbnail: str = None,
+        image: str = None,
+        author_name: str = None,
+        author_icon: str = None,
+        timestamp: bool = False,
+    ) -> dict:
+        """Build a Discord embed dict."""
+        embed = {"color": color}
+        if title:
+            embed["title"] = title
+        if description:
+            embed["description"] = description
+        if fields:
+            embed["fields"] = [
+                {"name": f["name"], "value": f["value"],
+                 "inline": f.get("inline", False)}
+                for f in fields
+            ]
+        if footer:
+            embed["footer"] = {"text": footer}
+        if thumbnail:
+            embed["thumbnail"] = {"url": thumbnail}
+        if image:
+            embed["image"] = {"url": image}
+        if author_name:
+            embed["author"] = {"name": author_name}
+            if author_icon:
+                embed["author"]["icon_url"] = author_icon
+        if timestamp:
+            embed["timestamp"] = datetime.datetime.utcnow().isoformat()
+        return embed
+
+    # ── Mention helpers ───────────────────────────────────────────────────────
+
+    @staticmethod
+    def mention_user(user_id: int) -> str:
+        return f"<@{user_id}>"
+
+    @staticmethod
+    def mention_role(role_id: int) -> str:
+        return f"<@&{role_id}>"
+
+    @staticmethod
+    def mention_channel(channel_id: int) -> str:
+        return f"<#{channel_id}>"
+
+    # ── ID parsing ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def parse_mention(mention: str) -> Optional[int]:
+        """Extract a raw ID from a Discord mention string."""
+        match = re.match(r"<[@&#!]{0,2}(\d+)>", mention)
+        return int(match.group(1)) if match else None
+
+    # ── Time helpers ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def discord_timestamp(dt: Union[datetime.datetime, int, float],
+                          style: str = "f") -> str:
+        """
+        Format a datetime as a Discord timestamp.
+        Styles: t, T, d, D, f, F, R
+        """
+        if isinstance(dt, datetime.datetime):
+            ts = int(dt.timestamp())
+        else:
+            ts = int(dt)
+        return f"<t:{ts}:{style}>"
+
+    @staticmethod
+    def time_until(seconds: int) -> str:
+        """Human-readable countdown string from seconds."""
+        periods = [
+            ("day", 86400),
+            ("hour", 3600),
+            ("minute", 60),
+            ("second", 1),
+        ]
+        parts = []
+        for name, period in periods:
+            value, seconds = divmod(seconds, period)
+            if value:
+                parts.append(f"{value} {name}{'s' if value != 1 else ''}")
+        return ", ".join(parts) if parts else "0 seconds"
+
+    # ── Snowflake ─────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def snowflake_to_timestamp(snowflake: int) -> datetime.datetime:
+        """Convert a Discord snowflake ID to a UTC datetime."""
+        timestamp_ms = (snowflake >> 22) + 1420070400000
+        return datetime.datetime.utcfromtimestamp(timestamp_ms / 1000)
+
+    # ── Permission helpers ────────────────────────────────────────────────────
+
+    PERMISSIONS = {
+        "administrator": 1 << 3,
+        "manage_guild": 1 << 5,
+        "manage_roles": 1 << 28,
+        "manage_channels": 1 << 4,
+        "kick_members": 1 << 1,
+        "ban_members": 1 << 2,
+        "manage_messages": 1 << 13,
+        "manage_webhooks": 1 << 29,
+        "manage_nicknames": 1 << 27,
+        "mention_everyone": 1 << 17,
+        "send_messages": 1 << 11,
+        "embed_links": 1 << 14,
+        "attach_files": 1 << 15,
+        "read_message_history": 1 << 16,
+        "connect": 1 << 20,
+        "speak": 1 << 21,
+        "mute_members": 1 << 22,
+        "deafen_members": 1 << 23,
+        "move_members": 1 << 24,
+    }
+
+    @classmethod
+    def has_permission(cls, permissions: int, permission_name: str) -> bool:
+        """Check if a permission bitfield includes a named permission."""
+        flag = cls.PERMISSIONS.get(permission_name.lower())
+        if flag is None:
+            raise ValueError(f"Unknown permission: {permission_name}")
+        return bool(permissions & cls.PERMISSIONS["administrator"] or permissions & flag)
+
+    @classmethod
+    def permissions_list(cls, permissions: int) -> list:
+        """Return a list of permission names from a bitfield."""
+        return [name for name, flag in cls.PERMISSIONS.items()
+                if permissions & flag]
+
+    # ── Text helpers ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def truncate(text: str, max_length: int = 2048, suffix: str = "...") -> str:
+        """Truncate text to fit Discord's limits."""
+        if len(text) <= max_length:
+            return text
+        return text[: max_length - len(suffix)] + suffix
+
+    @staticmethod
+    def code_block(content: str, language: str = "") -> str:
+        """Wrap content in a Discord code block."""
+        return f"```{language}\n{content}\n```"
+
+    @staticmethod
+    def inline_code(content: str) -> str:
+        return f"`{content}`"
+
+    @staticmethod
+    def bold(text: str) -> str:
+        return f"**{text}**"
+
+    @staticmethod
+    def italic(text: str) -> str:
+        return f"*{text}*"
+
+    @staticmethod
+    def underline(text: str) -> str:
+        return f"__{text}__"
+
+    @staticmethod
+    def strikethrough(text: str) -> str:
+        return f"~~{text}~~"
+
+    @staticmethod
+    def spoiler(text: str) -> str:
+        return f"||{text}||"

kroxy/website/__init__.py

@@ -0,0 +1,5 @@
+"""
+kroxy.website - Website utilities (coming soon).
+"""
+
+__all__ = []