nui-python-shared-utils 1.3.0__py3-none-any.whl

nui_lambda_shared_utils/slack_setup/channel_definitions.py

@@ -0,0 +1,187 @@
+"""
+Channel definition models and configuration parser.
+"""
+
+import os
+import yaml
+from typing import List, Dict, Optional, Any
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ChannelDefinition:
+    """Represents a Slack channel configuration."""
+
+    name: str
+    purpose: str
+    description: str
+    topic: str
+    invite_users: List[str] = field(default_factory=list)
+    service: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "name": self.name,
+            "purpose": self.purpose,
+            "description": self.description,
+            "topic": self.topic,
+            "invite_users": self.invite_users,
+            "service": self.service,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any], service: Optional[str] = None) -> "ChannelDefinition":
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            purpose=data["purpose"],
+            description=data["description"],
+            topic=data["topic"],
+            invite_users=data.get("invite_users", []),
+            service=service or data.get("service"),
+        )
+
+
+def load_channel_config(config_path: str) -> List[ChannelDefinition]:
+    """
+    Load channel definitions from YAML config file.
+
+    Args:
+        config_path: Path to YAML config file
+
+    Returns:
+        List of channel definitions
+
+    Example YAML:
+        service: business-insights
+        default_invite_users:
+          - tim
+        channels:
+          - name: insights-daily
+            purpose: Daily operational metrics
+            description: Daily business insights for platform operations
+            topic: 📊 Daily business metrics
+          - name: insights-executive
+            purpose: Executive summaries
+            description: Weekly executive reports
+            topic: 🎯 Weekly executive summaries
+            invite_users:
+              - tim
+              - john
+    """
+    if not os.path.exists(config_path):
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with open(config_path, "r") as f:
+        config = yaml.safe_load(f)
+
+    if not config or "channels" not in config:
+        raise ValueError("Invalid config file: missing 'channels' section")
+
+    service = config.get("service")
+    default_invite_users = config.get("default_invite_users", [])
+
+    definitions = []
+    for channel_data in config["channels"]:
+        # Apply defaults
+        if "invite_users" not in channel_data and default_invite_users:
+            channel_data["invite_users"] = default_invite_users
+
+        definition = ChannelDefinition.from_dict(channel_data, service)
+        definitions.append(definition)
+
+    return definitions
+
+
+def generate_serverless_config(channel_map: Dict[str, str], service_name: str, output_format: str = "yaml") -> str:
+    """
+    Generate serverless.yml configuration snippet.
+
+    Args:
+        channel_map: Dict mapping channel names to IDs
+        service_name: Name of the service
+        output_format: 'yaml' or 'env'
+
+    Returns:
+        Configuration snippet
+    """
+    if output_format == "yaml":
+        lines = ["# Add this to your serverless.yml custom section:", "custom:", "  slack:", "    channels:"]
+
+        # Map channel names to config keys
+        key_mapping = {
+            "alerts": "alerts",
+            "health": "health",
+            "debug": "debug",
+            "daily": "daily",
+            "weekly": "weekly",
+            "executive": "executive",
+            "insights": "insights",
+            "operations": "operations",
+            "activity": "activity",
+        }
+
+        for channel_name, channel_id in channel_map.items():
+            # Extract key from channel name
+            key = None
+            for keyword, config_key in key_mapping.items():
+                if keyword in channel_name:
+                    key = config_key
+                    break
+
+            if not key:
+                # Default to last part of channel name
+                key = channel_name.split("-")[-1]
+
+            lines.append(f'      {key}: "{channel_id}"  # {channel_name}')
+
+        return "\n".join(lines)
+
+    elif output_format == "env":
+        lines = [
+            "# Environment variables for your application:",
+        ]
+
+        for channel_name, channel_id in channel_map.items():
+            env_key = channel_name.upper().replace("-", "_") + "_CHANNEL"
+            lines.append(f"{env_key}={channel_id}")
+
+        return "\n".join(lines)
+
+    else:
+        raise ValueError(f"Unknown output format: {output_format}")
+
+
+def validate_channel_names(definitions: List[ChannelDefinition]) -> List[str]:
+    """
+    Validate channel names according to Slack rules.
+
+    Args:
+        definitions: List of channel definitions
+
+    Returns:
+        List of validation errors (empty if all valid)
+    """
+    errors = []
+
+    for definition in definitions:
+        name = definition.name
+
+        # Check length
+        if len(name) > 80:
+            errors.append(f"{name}: Channel name too long (max 80 chars)")
+
+        # Check for valid characters
+        if not all(c.isalnum() or c in "-_" for c in name):
+            errors.append(f"{name}: Invalid characters (use only letters, numbers, hyphens, underscores)")
+
+        # Check lowercase
+        if name != name.lower():
+            errors.append(f"{name}: Channel names must be lowercase")
+
+        # Check doesn't start with special chars
+        if name and name[0] in "-_":
+            errors.append(f"{name}: Channel name cannot start with hyphen or underscore")
+
+    return errors

nui_lambda_shared_utils/slack_setup/setup_helpers.py

@@ -0,0 +1,211 @@
+"""
+Helper functions for Slack setup operations.
+"""
+
+import os
+import sys
+import logging
+from typing import List, Dict, Optional
+from slack_sdk import WebClient
+from slack_sdk.errors import SlackApiError
+
+log = logging.getLogger(__name__)
+
+
+class SlackSetupHelper:
+    """Helper utilities for Slack setup operations."""
+
+    def __init__(self, token: Optional[str] = None):
+        """Initialize with Slack token."""
+        self.token = token or os.environ.get("SLACK_BOT_TOKEN")
+        if not self.token:
+            raise ValueError("No Slack bot token provided")
+
+        self.client = WebClient(token=self.token)
+
+    def test_channel_access(self, channel_ids: List[str]) -> Dict[str, bool]:
+        """
+        Test if bot can post to channels.
+
+        Args:
+            channel_ids: List of channel IDs to test
+
+        Returns:
+            Dict mapping channel IDs to success status
+        """
+        results = {}
+
+        for channel_id in channel_ids:
+            try:
+                self.client.chat_postMessage(channel=channel_id, text="🔧 Testing channel access...")
+                results[channel_id] = True
+                log.info(f"✅ Can post to channel {channel_id}")
+            except SlackApiError as e:
+                results[channel_id] = False
+                log.error(f"❌ Cannot post to channel {channel_id}: {e.response['error']}")
+
+        return results
+
+    def get_channel_info(self, channel_id: str) -> Optional[Dict]:
+        """Get detailed channel information."""
+        try:
+            response = self.client.conversations_info(channel=channel_id)
+            return response["channel"]
+        except SlackApiError as e:
+            log.error(f"Error getting channel info: {e}")
+            return None
+
+    def list_bot_channels(self) -> List[Dict]:
+        """List all channels the bot is a member of."""
+        channels = []
+        cursor = None
+
+        try:
+            while True:
+                response = self.client.conversations_list(exclude_archived=True, types="public_channel", cursor=cursor)
+
+                # Filter to only channels bot is member of
+                for channel in response["channels"]:
+                    if channel.get("is_member", False):
+                        channels.append(
+                            {
+                                "id": channel["id"],
+                                "name": channel["name"],
+                                "purpose": channel.get("purpose", {}).get("value", ""),
+                                "topic": channel.get("topic", {}).get("value", ""),
+                                "num_members": channel.get("num_members", 0),
+                            }
+                        )
+
+                cursor = response.get("response_metadata", {}).get("next_cursor")
+                if not cursor:
+                    break
+
+        except SlackApiError as e:
+            log.error(f"Error listing channels: {e}")
+
+        return channels
+
+    def validate_bot_permissions(self) -> Dict[str, bool]:
+        """Check if bot has required permissions."""
+        required_scopes = ["channels:manage", "channels:join", "chat:write", "channels:read", "users:read"]
+
+        try:
+            response = self.client.auth_test()
+            # Note: auth.test doesn't return scopes in newer apps
+            # This would need to be checked via the app's OAuth settings
+
+            return {
+                "authenticated": True,
+                "bot_id": response.get("user_id"),
+                "bot_name": response.get("user"),
+                "team": response.get("team"),
+                "url": response.get("url"),
+            }
+
+        except SlackApiError as e:
+            log.error(f"Auth test failed: {e}")
+            return {"authenticated": False, "error": str(e)}
+
+
+def prompt_for_token() -> str:
+    """Interactive prompt for Slack bot token."""
+    print("\n" + "=" * 60)
+    print("Slack Bot Token Required")
+    print("=" * 60)
+    print("\nTo get your bot token:")
+    print("1. Go to https://api.slack.com/apps")
+    print("2. Select your app (or create a new one)")
+    print("3. Go to 'OAuth & Permissions'")
+    print("4. Copy the 'Bot User OAuth Token' (starts with xoxb-)")
+    print("\nRequired OAuth Scopes:")
+    print("  - channels:manage    (create channels)")
+    print("  - channels:join      (join channels)")
+    print("  - chat:write         (send messages)")
+    print("  - channels:read      (list channels)")
+    print("  - users:read         (look up users)")
+    print("  - channels:write.invites (invite users)")
+    print("\n" + "=" * 60)
+
+    token = input("\nEnter Bot Token (xoxb-...): ").strip()
+
+    if not token.startswith("xoxb-"):
+        print("\n⚠️  Warning: Token doesn't start with 'xoxb-'")
+        confirm = input("Continue anyway? (y/n): ")
+        if confirm.lower() != "y":
+            sys.exit(1)
+
+    return token
+
+
+def print_channel_summary(channel_map: Dict[str, str], service_name: str):
+    """Print summary of created channels."""
+    print("\n" + "=" * 60)
+    print(f"Channel Setup Complete for {service_name}")
+    print("=" * 60)
+
+    if not channel_map:
+        print("\n❌ No channels were created")
+        return
+
+    print("\n✅ Channels ready:")
+    for name, channel_id in channel_map.items():
+        print(f"  #{name:<30} ID: {channel_id}")
+
+    print("\n📋 Next steps:")
+    print("1. Use the channel IDs in your application configuration")
+    print("2. Deploy your application")
+    print("3. Test by sending messages to the channels")
+
+    print("\n💡 Tips:")
+    print("- Bot is already in all channels")
+    print("- Invited users have been added to channels")
+    print("- Channels are public for transparency")
+
+
+def confirm_channel_creation(definitions: List["ChannelDefinition"], existing: Dict[str, Optional[str]]) -> bool:
+    """
+    Interactive confirmation for channel creation.
+
+    Args:
+        definitions: Channel definitions to create
+        existing: Map of existing channels
+
+    Returns:
+        True if user confirms, False otherwise
+    """
+    print("\n" + "=" * 60)
+    print("Channel Creation Plan")
+    print("=" * 60)
+
+    to_create = []
+    already_exist = []
+
+    for definition in definitions:
+        if existing.get(definition.name):
+            already_exist.append(definition)
+        else:
+            to_create.append(definition)
+
+    if already_exist:
+        print("\n✅ Existing channels (will configure/join):")
+        for definition in already_exist:
+            print(f"  #{definition.name}")
+            print(f"    Purpose: {definition.purpose}")
+
+    if to_create:
+        print("\n🆕 Channels to create:")
+        for definition in to_create:
+            print(f"  #{definition.name}")
+            print(f"    Purpose: {definition.purpose}")
+            print(f"    Topic: {definition.topic}")
+            if definition.invite_users:
+                print(f"    Inviting: {', '.join(definition.invite_users)}")
+
+    if not to_create and not already_exist:
+        print("\n❌ No channels to process")
+        return False
+
+    print("\n" + "=" * 60)
+    response = input("\nProceed with channel setup? (y/n): ")
+    return response.lower() == "y"

nui_lambda_shared_utils/timezone.py

@@ -0,0 +1,117 @@
+"""
+Timezone utilities for multi-timezone handling (NZ primary, AUS/US/EUR secondary).
+"""
+
+from datetime import datetime, timezone
+import pytz
+from typing import List, Tuple, Optional
+
+# Supported timezones
+NZ_TZ = pytz.timezone("Pacific/Auckland")  # Primary timezone
+AUS_TZ = pytz.timezone("Australia/Sydney")
+US_EAST_TZ = pytz.timezone("US/Eastern")
+US_WEST_TZ = pytz.timezone("US/Pacific")
+EUR_TZ = pytz.timezone("Europe/London")
+
+
+def nz_time(utc_dt: Optional[datetime] = None) -> datetime:
+    """
+    Convert UTC datetime to NZ time or get current NZ time.
+
+    Args:
+        utc_dt: UTC datetime to convert (defaults to now)
+
+    Returns:
+        Datetime in NZ timezone
+    """
+    if utc_dt is None:
+        utc_dt = datetime.now(timezone.utc)
+
+    if utc_dt.tzinfo is None:
+        utc_dt = pytz.UTC.localize(utc_dt)
+
+    return utc_dt.astimezone(NZ_TZ)
+
+
+def format_nz_time(dt: Optional[datetime] = None, fmt: str = "%Y-%m-%d %H:%M:%S %Z") -> str:
+    """
+    Format datetime as NZ time string.
+
+    Args:
+        dt: Datetime to format (defaults to now)
+        fmt: strftime format string
+
+    Returns:
+        Formatted time string
+    """
+    nz_dt = nz_time(dt)
+    return nz_dt.strftime(fmt)
+
+
+def format_multi_timezone(dt: Optional[datetime] = None, primary_tz: str = "nz", secondary_tz: str = "aus") -> str:
+    """
+    Format datetime with primary and secondary timezone display.
+
+    Example output: "Fri 26th 10am NZDT (Thu 8pm AEDT)"
+
+    Args:
+        dt: Datetime to format (defaults to now)
+        primary_tz: Primary timezone ("nz", "aus", "us_east", "us_west", "eur")
+        secondary_tz: Secondary timezone for parenthetical display
+
+    Returns:
+        Formatted multi-timezone string
+    """
+    if dt is None:
+        dt = datetime.now(timezone.utc)
+
+    if dt.tzinfo is None:
+        dt = pytz.UTC.localize(dt)
+
+    # Timezone mapping
+    tz_map = {"nz": NZ_TZ, "aus": AUS_TZ, "us_east": US_EAST_TZ, "us_west": US_WEST_TZ, "eur": EUR_TZ}
+
+    primary_tzinfo = tz_map.get(primary_tz, NZ_TZ)
+    secondary_tzinfo = tz_map.get(secondary_tz, AUS_TZ)
+
+    # Convert to both timezones
+    primary_dt = dt.astimezone(primary_tzinfo)
+    secondary_dt = dt.astimezone(secondary_tzinfo)
+
+    # Format primary timezone with ordinal
+    def format_ordinal(day):
+        if 10 <= day % 100 <= 20:
+            suffix = "th"
+        else:
+            suffix = {1: "st", 2: "nd", 3: "rd"}.get(day % 10, "th")
+        return f"{day}{suffix}"
+
+    # Primary format: "Fri 26th 10am NZDT"
+    primary_hour = primary_dt.strftime("%I").lstrip("0") or "12"
+    primary_tz_abbr = primary_dt.strftime("%Z")
+    primary_formatted = f"{primary_dt.strftime('%a')} {format_ordinal(primary_dt.day)} {primary_hour}{primary_dt.strftime('%p').lower()} {primary_tz_abbr}"
+
+    # Secondary format: "Thu 8pm AEDT"
+    secondary_hour = secondary_dt.strftime("%I").lstrip("0") or "12"
+    secondary_tz_abbr = secondary_dt.strftime("%Z")
+    secondary_formatted = (
+        f"{secondary_dt.strftime('%a')} {secondary_hour}{secondary_dt.strftime('%p').lower()} {secondary_tz_abbr}"
+    )
+
+    return f"{primary_formatted} ({secondary_formatted})"
+
+
+def get_timezone_options() -> List[Tuple[str, str]]:
+    """
+    Get available timezone options for configuration.
+
+    Returns:
+        List of (key, description) tuples
+    """
+    return [
+        ("nz", "New Zealand (Pacific/Auckland)"),
+        ("aus", "Australia (Australia/Sydney)"),
+        ("us_east", "US Eastern (US/Eastern)"),
+        ("us_west", "US Pacific (US/Pacific)"),
+        ("eur", "Europe (Europe/London)"),
+    ]