kroxy 0.1.0__py3-none-any.whl

kroxy/__init__.py

@@ -0,0 +1,13 @@
+"""
+kroxy - A professional Python utility library.
+Author: @kroxy
+"""
+
+__version__ = "0.1.0"
+__author__ = "kroxy"
+__license__ = "MIT"
+
+from kroxy import discord
+from kroxy import website
+
+__all__ = ["discord", "website"]

kroxy/discord/__init__.py

@@ -0,0 +1,22 @@
+"""
+kroxy.discord - Professional Discord utilities and helpers.
+"""
+
+from kroxy.discord.api import DiscordAPI
+from kroxy.discord.commands import SlashCommand, PrefixCommand
+from kroxy.discord.utils import Utils
+from kroxy.discord.antinuke import AntiNuke
+from kroxy.discord.checkers import Checkers
+from kroxy.discord.giveaway import Giveaway
+from kroxy.discord.music import MusicPlayer
+
+__all__ = [
+    "DiscordAPI",
+    "SlashCommand",
+    "PrefixCommand",
+    "Utils",
+    "AntiNuke",
+    "Checkers",
+    "Giveaway",
+    "MusicPlayer",
+]

kroxy/discord/antinuke.py

@@ -0,0 +1,146 @@
+"""
+kroxy.discord.antinuke - Anti-nuke protection system for Discord servers.
+"""
+
+import asyncio
+import time
+from collections import defaultdict
+from typing import Dict, List, Optional, Callable, Any
+
+
+class ActionLog:
+    """Tracks recent actions per user for rate-limit detection."""
+
+    def __init__(self, threshold: int, window: int):
+        self.threshold = threshold
+        self.window = window  # seconds
+        self._log: Dict[int, List[float]] = defaultdict(list)
+
+    def record(self, user_id: int) -> int:
+        """Record an action and return the count within the window."""
+        now = time.time()
+        self._log[user_id] = [t for t in self._log[user_id] if now - t < self.window]
+        self._log[user_id].append(now)
+        return len(self._log[user_id])
+
+    def exceeded(self, user_id: int) -> bool:
+        """Return True if the user has exceeded the threshold."""
+        return self.record(user_id) >= self.threshold
+
+    def reset(self, user_id: int):
+        self._log.pop(user_id, None)
+
+
+class AntiNuke:
+    """
+    Anti-nuke system that monitors destructive actions and auto-punishes abusers.
+
+    Usage:
+        antinuke = AntiNuke(bot, whitelist=[owner_id])
+        antinuke.on_trigger = my_punishment_callback
+    """
+
+    DEFAULT_LIMITS = {
+        "ban": (3, 10),           # 3 bans in 10s
+        "kick": (3, 10),
+        "channel_delete": (3, 10),
+        "channel_create": (5, 10),
+        "role_delete": (3, 10),
+        "role_create": (5, 10),
+        "webhook_create": (3, 10),
+        "webhook_delete": (3, 10),
+        "invite_delete": (5, 10),
+        "mass_mention": (5, 5),
+        "bot_add": (2, 30),
+    }
+
+    def __init__(self, whitelist: List[int] = None, limits: Dict = None):
+        self.whitelist: List[int] = whitelist or []
+        limits = limits or {}
+        merged = {**self.DEFAULT_LIMITS, **limits}
+        self._trackers: Dict[str, ActionLog] = {
+            action: ActionLog(threshold, window)
+            for action, (threshold, window) in merged.items()
+        }
+        self._punished: set = set()
+        self.on_trigger: Optional[Callable] = None
+        self.punishment: str = "ban"  # "ban" | "kick" | "strip_roles"
+
+    def is_whitelisted(self, user_id: int) -> bool:
+        return user_id in self.whitelist
+
+    def add_whitelist(self, user_id: int):
+        if user_id not in self.whitelist:
+            self.whitelist.append(user_id)
+
+    def remove_whitelist(self, user_id: int):
+        self.whitelist = [u for u in self.whitelist if u != user_id]
+
+    async def check(self, action: str, user_id: int, guild: Any = None) -> bool:
+        """
+        Check an action for a user. Returns True if limit exceeded.
+        Calls self.on_trigger(action, user_id, guild) if set.
+        """
+        if self.is_whitelisted(user_id):
+            return False
+        if user_id in self._punished:
+            return True
+
+        tracker = self._trackers.get(action)
+        if tracker is None:
+            return False
+
+        if tracker.exceeded(user_id):
+            self._punished.add(user_id)
+            if self.on_trigger:
+                try:
+                    await self.on_trigger(action=action, user_id=user_id, guild=guild)
+                except Exception:
+                    pass
+            return True
+        return False
+
+    def reset_user(self, user_id: int):
+        """Clear all action logs and punishment flag for a user."""
+        for tracker in self._trackers.values():
+            tracker.reset(user_id)
+        self._punished.discard(user_id)
+
+    def get_stats(self) -> Dict:
+        """Return current limits configuration."""
+        return {
+            action: {"threshold": t.threshold, "window": t.window}
+            for action, t in self._trackers.items()
+        }
+
+    # ── Convenience event handlers (wire these to your event system) ──────────
+
+    async def on_member_ban(self, user_id: int, guild: Any = None):
+        return await self.check("ban", user_id, guild)
+
+    async def on_member_kick(self, user_id: int, guild: Any = None):
+        return await self.check("kick", user_id, guild)
+
+    async def on_channel_delete(self, user_id: int, guild: Any = None):
+        return await self.check("channel_delete", user_id, guild)
+
+    async def on_channel_create(self, user_id: int, guild: Any = None):
+        return await self.check("channel_create", user_id, guild)
+
+    async def on_role_delete(self, user_id: int, guild: Any = None):
+        return await self.check("role_delete", user_id, guild)
+
+    async def on_role_create(self, user_id: int, guild: Any = None):
+        return await self.check("role_create", user_id, guild)
+
+    async def on_webhook_create(self, user_id: int, guild: Any = None):
+        return await self.check("webhook_create", user_id, guild)
+
+    async def on_webhook_delete(self, user_id: int, guild: Any = None):
+        return await self.check("webhook_delete", user_id, guild)
+
+    async def on_bot_add(self, user_id: int, guild: Any = None):
+        return await self.check("bot_add", user_id, guild)
+
+    async def on_mass_mention(self, user_id: int, guild: Any = None):
+        return await self.check("mass_mention", user_id, guild)

kroxy/discord/api.py

@@ -0,0 +1,128 @@
+"""
+kroxy.discord.api - Discord REST API wrapper helpers.
+"""
+
+import aiohttp
+import asyncio
+from typing import Optional, Any, Dict
+
+DISCORD_API_BASE = "https://discord.com/api/v10"
+
+
+class DiscordAPI:
+    """Async Discord REST API client."""
+
+    def __init__(self, token: str, bot: bool = True):
+        prefix = "Bot" if bot else "Bearer"
+        self.headers = {
+            "Authorization": f"{prefix} {token}",
+            "Content-Type": "application/json",
+        }
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(headers=self.headers)
+        return self._session
+
+    async def close(self):
+        """Close the underlying HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def request(self, method: str, endpoint: str, **kwargs) -> Any:
+        """Make a raw API request."""
+        session = await self._get_session()
+        url = f"{DISCORD_API_BASE}{endpoint}"
+        async with session.request(method, url, **kwargs) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+    async def get_guild(self, guild_id: int) -> Dict:
+        """Fetch a guild by ID."""
+        return await self.request("GET", f"/guilds/{guild_id}")
+
+    async def get_channel(self, channel_id: int) -> Dict:
+        """Fetch a channel by ID."""
+        return await self.request("GET", f"/channels/{channel_id}")
+
+    async def get_user(self, user_id: int) -> Dict:
+        """Fetch a user by ID."""
+        return await self.request("GET", f"/users/{user_id}")
+
+    async def send_message(self, channel_id: int, content: str = None,
+                           embed: Dict = None, components: list = None) -> Dict:
+        """Send a message to a channel."""
+        payload: Dict[str, Any] = {}
+        if content:
+            payload["content"] = content
+        if embed:
+            payload["embeds"] = [embed]
+        if components:
+            payload["components"] = components
+        return await self.request("POST", f"/channels/{channel_id}/messages", json=payload)
+
+    async def delete_message(self, channel_id: int, message_id: int) -> None:
+        """Delete a message."""
+        await self.request("DELETE", f"/channels/{channel_id}/messages/{message_id}")
+
+    async def ban_member(self, guild_id: int, user_id: int,
+                         reason: str = None, delete_message_days: int = 0) -> None:
+        """Ban a member from a guild."""
+        payload = {"delete_message_days": delete_message_days}
+        headers = {}
+        if reason:
+            headers["X-Audit-Log-Reason"] = reason
+        await self.request("PUT", f"/guilds/{guild_id}/bans/{user_id}",
+                           json=payload, headers=headers)
+
+    async def unban_member(self, guild_id: int, user_id: int) -> None:
+        """Unban a member."""
+        await self.request("DELETE", f"/guilds/{guild_id}/bans/{user_id}")
+
+    async def kick_member(self, guild_id: int, user_id: int, reason: str = None) -> None:
+        """Kick a member from a guild."""
+        headers = {}
+        if reason:
+            headers["X-Audit-Log-Reason"] = reason
+        await self.request("DELETE", f"/guilds/{guild_id}/members/{user_id}",
+                           headers=headers)
+
+    async def add_role(self, guild_id: int, user_id: int, role_id: int) -> None:
+        """Add a role to a member."""
+        await self.request("PUT", f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}")
+
+    async def remove_role(self, guild_id: int, user_id: int, role_id: int) -> None:
+        """Remove a role from a member."""
+        await self.request("DELETE", f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}")
+
+    async def create_channel(self, guild_id: int, name: str,
+                             channel_type: int = 0, **kwargs) -> Dict:
+        """Create a guild channel."""
+        payload = {"name": name, "type": channel_type, **kwargs}
+        return await self.request("POST", f"/guilds/{guild_id}/channels", json=payload)
+
+    async def delete_channel(self, channel_id: int) -> Dict:
+        """Delete a channel."""
+        return await self.request("DELETE", f"/channels/{channel_id}")
+
+    async def get_audit_logs(self, guild_id: int, limit: int = 50) -> Dict:
+        """Fetch guild audit logs."""
+        return await self.request("GET", f"/guilds/{guild_id}/audit-logs",
+                                  params={"limit": limit})
+
+    async def get_invites(self, guild_id: int) -> list:
+        """Get all guild invites."""
+        return await self.request("GET", f"/guilds/{guild_id}/invites")
+
+    async def delete_invite(self, invite_code: str) -> None:
+        """Delete an invite by code."""
+        await self.request("DELETE", f"/invites/{invite_code}")
+
+    async def get_webhooks(self, guild_id: int) -> list:
+        """Get all webhooks in a guild."""
+        return await self.request("GET", f"/guilds/{guild_id}/webhooks")
+
+    async def delete_webhook(self, webhook_id: int) -> None:
+        """Delete a webhook."""
+        await self.request("DELETE", f"/webhooks/{webhook_id}")

kroxy/discord/checkers.py

@@ -0,0 +1,159 @@
+"""
+kroxy.discord.checkers - Permission and role check utilities.
+"""
+
+from typing import List, Union, Any, Optional
+
+
+class CheckFailed(Exception):
+    """Raised when a permission/role check fails."""
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+class Checkers:
+    """
+    Collection of Discord permission and role checks.
+    Each method raises CheckFailed on failure or returns True on success.
+    """
+
+    # ── Permission checks ─────────────────────────────────────────────────────
+
+    @staticmethod
+    def has_permission(member_permissions: int, permission_flag: int,
+                       admin_bypass: bool = True) -> bool:
+        """Check if a permissions bitfield includes a flag."""
+        admin_flag = 1 << 3
+        if admin_bypass and (member_permissions & admin_flag):
+            return True
+        return bool(member_permissions & permission_flag)
+
+    @staticmethod
+    def require_permission(member_permissions: int, permission_flag: int,
+                           permission_name: str = "required permission") -> bool:
+        if not Checkers.has_permission(member_permissions, permission_flag):
+            raise CheckFailed(f"You need the `{permission_name}` permission.")
+        return True
+
+    @staticmethod
+    def require_admin(member_permissions: int) -> bool:
+        admin_flag = 1 << 3
+        if not (member_permissions & admin_flag):
+            raise CheckFailed("You need the `Administrator` permission.")
+        return True
+
+    @staticmethod
+    def require_manage_guild(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 5, "Manage Server")
+
+    @staticmethod
+    def require_manage_roles(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 28, "Manage Roles")
+
+    @staticmethod
+    def require_ban_members(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 2, "Ban Members")
+
+    @staticmethod
+    def require_kick_members(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 1, "Kick Members")
+
+    @staticmethod
+    def require_manage_channels(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 4, "Manage Channels")
+
+    @staticmethod
+    def require_manage_messages(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 13, "Manage Messages")
+
+    @staticmethod
+    def require_manage_webhooks(member_permissions: int) -> bool:
+        return Checkers.require_permission(member_permissions, 1 << 29, "Manage Webhooks")
+
+    # ── Role checks ───────────────────────────────────────────────────────────
+
+    @staticmethod
+    def has_role(member_role_ids: List[int], role_id: int) -> bool:
+        """Check if a member has a specific role."""
+        return role_id in member_role_ids
+
+    @staticmethod
+    def has_any_role(member_role_ids: List[int], role_ids: List[int]) -> bool:
+        """Check if a member has at least one of the given roles."""
+        return bool(set(member_role_ids) & set(role_ids))
+
+    @staticmethod
+    def has_all_roles(member_role_ids: List[int], role_ids: List[int]) -> bool:
+        """Check if a member has all of the given roles."""
+        return set(role_ids).issubset(set(member_role_ids))
+
+    @staticmethod
+    def require_role(member_role_ids: List[int], role_id: int,
+                     role_name: str = "a required role") -> bool:
+        if not Checkers.has_role(member_role_ids, role_id):
+            raise CheckFailed(f"You need the **{role_name}** role.")
+        return True
+
+    @staticmethod
+    def require_any_role(member_role_ids: List[int], role_ids: List[int]) -> bool:
+        if not Checkers.has_any_role(member_role_ids, role_ids):
+            raise CheckFailed("You don't have any of the required roles.")
+        return True
+
+    # ── Hierarchy checks ──────────────────────────────────────────────────────
+
+    @staticmethod
+    def check_hierarchy(executor_top_role_pos: int, target_top_role_pos: int,
+                        bot_top_role_pos: int) -> bool:
+        """
+        Ensure the executor and bot are higher than the target in the role hierarchy.
+        Raises CheckFailed on violation.
+        """
+        if target_top_role_pos >= executor_top_role_pos:
+            raise CheckFailed("You cannot perform this action on someone with an equal or higher role.")
+        if target_top_role_pos >= bot_top_role_pos:
+            raise CheckFailed("I cannot perform this action on someone with a role equal to or higher than mine.")
+        return True
+
+    # ── Guild-level checks ────────────────────────────────────────────────────
+
+    @staticmethod
+    def is_guild_owner(user_id: int, guild_owner_id: int) -> bool:
+        return user_id == guild_owner_id
+
+    @staticmethod
+    def require_guild_owner(user_id: int, guild_owner_id: int) -> bool:
+        if not Checkers.is_guild_owner(user_id, guild_owner_id):
+            raise CheckFailed("Only the server owner can use this command.")
+        return True
+
+    @staticmethod
+    def is_bot(is_bot_flag: bool) -> bool:
+        return is_bot_flag
+
+    @staticmethod
+    def block_bots(is_bot_flag: bool) -> bool:
+        if is_bot_flag:
+            raise CheckFailed("Bots cannot use this command.")
+        return True
+
+    # ── Channel checks ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def require_guild_only(guild_id: Optional[int]) -> bool:
+        if guild_id is None:
+            raise CheckFailed("This command can only be used in a server.")
+        return True
+
+    @staticmethod
+    def require_dm_only(guild_id: Optional[int]) -> bool:
+        if guild_id is not None:
+            raise CheckFailed("This command can only be used in DMs.")
+        return True
+
+    @staticmethod
+    def require_nsfw(channel_is_nsfw: bool) -> bool:
+        if not channel_is_nsfw:
+            raise CheckFailed("This command can only be used in NSFW channels.")
+        return True

kroxy/discord/commands.py

@@ -0,0 +1,187 @@
+"""
+kroxy.discord.commands - Slash and prefix command builders.
+"""
+
+from typing import Callable, Optional, List, Dict, Any
+import functools
+
+
+class Option:
+    """Represents a slash command option."""
+
+    TYPES = {
+        "sub_command": 1,
+        "sub_command_group": 2,
+        "string": 3,
+        "integer": 4,
+        "boolean": 5,
+        "user": 6,
+        "channel": 7,
+        "role": 8,
+        "mentionable": 9,
+        "number": 10,
+        "attachment": 11,
+    }
+
+    def __init__(self, name: str, description: str, option_type: str = "string",
+                 required: bool = False, choices: List[Dict] = None):
+        self.name = name
+        self.description = description
+        self.type = self.TYPES.get(option_type, 3)
+        self.required = required
+        self.choices = choices or []
+
+    def to_dict(self) -> Dict:
+        data = {
+            "name": self.name,
+            "description": self.description,
+            "type": self.type,
+            "required": self.required,
+        }
+        if self.choices:
+            data["choices"] = self.choices
+        return data
+
+
+class SlashCommand:
+    """Slash command builder and decorator."""
+
+    def __init__(self, name: str, description: str,
+                 options: List[Option] = None,
+                 default_member_permissions: Optional[str] = None,
+                 dm_permission: bool = True):
+        self.name = name
+        self.description = description
+        self.options = options or []
+        self.default_member_permissions = default_member_permissions
+        self.dm_permission = dm_permission
+        self._callback: Optional[Callable] = None
+
+    def __call__(self, func: Callable):
+        self._callback = func
+        functools.update_wrapper(self, func)
+        return self
+
+    async def invoke(self, interaction: Any, **kwargs):
+        """Invoke the command callback."""
+        if self._callback is None:
+            raise RuntimeError(f"No callback set for slash command '{self.name}'")
+        return await self._callback(interaction, **kwargs)
+
+    def to_dict(self) -> Dict:
+        data = {
+            "name": self.name,
+            "description": self.description,
+            "options": [opt.to_dict() for opt in self.options],
+            "dm_permission": self.dm_permission,
+        }
+        if self.default_member_permissions is not None:
+            data["default_member_permissions"] = self.default_member_permissions
+        return data
+
+    @staticmethod
+    def decorator(name: str, description: str, options: List[Option] = None,
+                  permissions: str = None):
+        """Decorator factory for slash commands."""
+        def wrapper(func: Callable) -> SlashCommand:
+            cmd = SlashCommand(
+                name=name,
+                description=description,
+                options=options,
+                default_member_permissions=permissions,
+            )
+            cmd._callback = func
+            return cmd
+        return wrapper
+
+
+class PrefixCommand:
+    """Prefix (text-based) command builder and decorator."""
+
+    def __init__(self, name: str, aliases: List[str] = None,
+                 description: str = "", cooldown: int = 0,
+                 required_permissions: List[str] = None):
+        self.name = name
+        self.aliases = aliases or []
+        self.description = description
+        self.cooldown = cooldown
+        self.required_permissions = required_permissions or []
+        self._callback: Optional[Callable] = None
+        self._cooldowns: Dict[int, float] = {}
+
+    def __call__(self, func: Callable):
+        self._callback = func
+        functools.update_wrapper(self, func)
+        return self
+
+    async def invoke(self, ctx: Any, *args, **kwargs):
+        """Invoke the command with cooldown check."""
+        import time
+        if self.cooldown > 0:
+            user_id = getattr(ctx.author, "id", 0)
+            last_used = self._cooldowns.get(user_id, 0)
+            now = time.time()
+            if now - last_used < self.cooldown:
+                remaining = self.cooldown - (now - last_used)
+                raise CooldownError(f"Command on cooldown. Try again in {remaining:.1f}s.")
+            self._cooldowns[user_id] = now
+
+        if self._callback is None:
+            raise RuntimeError(f"No callback set for prefix command '{self.name}'")
+        return await self._callback(ctx, *args, **kwargs)
+
+    @staticmethod
+    def decorator(name: str, aliases: List[str] = None,
+                  description: str = "", cooldown: int = 0,
+                  permissions: List[str] = None):
+        """Decorator factory for prefix commands."""
+        def wrapper(func: Callable) -> PrefixCommand:
+            cmd = PrefixCommand(
+                name=name,
+                aliases=aliases,
+                description=description,
+                cooldown=cooldown,
+                required_permissions=permissions,
+            )
+            cmd._callback = func
+            return cmd
+        return wrapper
+
+
+class CooldownError(Exception):
+    """Raised when a command is on cooldown."""
+    pass
+
+
+class CommandRegistry:
+    """Registry to manage all slash and prefix commands."""
+
+    def __init__(self):
+        self._slash: Dict[str, SlashCommand] = {}
+        self._prefix: Dict[str, PrefixCommand] = {}
+
+    def add_slash(self, command: SlashCommand):
+        self._slash[command.name] = command
+
+    def add_prefix(self, command: PrefixCommand):
+        self._prefix[command.name] = command
+        for alias in command.aliases:
+            self._prefix[alias] = command
+
+    def get_slash(self, name: str) -> Optional[SlashCommand]:
+        return self._slash.get(name)
+
+    def get_prefix(self, name: str) -> Optional[PrefixCommand]:
+        return self._prefix.get(name)
+
+    def all_slash(self) -> List[SlashCommand]:
+        return list(self._slash.values())
+
+    def all_prefix(self) -> List[PrefixCommand]:
+        seen = set()
+        result = []
+        for cmd in self._prefix.values():
+            if cmd.name not in seen:
+                seen.add(cmd.name)
+                result.append(cmd)
+        return result