discord_rda 0.1.3

data/lib/discord_rda/entity/channel.rb

@@ -0,0 +1,446 @@
+# frozen_string_literal: true
+
+module DiscordRDA
+  # Represents a Discord channel.
+  # Can be text, voice, category, DM, thread, etc.
+  #
+  class Channel < Entity
+    # Channel types
+    TYPES = {
+      guild_text: 0,
+      dm: 1,
+      guild_voice: 2,
+      group_dm: 3,
+      guild_category: 4,
+      guild_announcement: 5,
+      announcement_thread: 10,
+      public_thread: 11,
+      private_thread: 12,
+      guild_stage_voice: 13,
+      guild_directory: 14,
+      guild_forum: 15,
+      guild_media: 16
+    }.freeze
+
+    attribute :type, type: :integer
+    attribute :guild_id, type: :snowflake
+    attribute :position, type: :integer, default: 0
+    attribute :name, type: :string
+    attribute :topic, type: :string
+    attribute :nsfw, type: :boolean, default: false
+    attribute :last_message_id, type: :snowflake
+    attribute :bitrate, type: :integer
+    attribute :user_limit, type: :integer
+    attribute :rate_limit_per_user, type: :integer, default: 0
+    attribute :recipients, type: :array, default: []
+    attribute :icon, type: :string
+    attribute :owner_id, type: :snowflake
+    attribute :application_id, type: :snowflake
+    attribute :parent_id, type: :snowflake
+    attribute :last_pin_timestamp, type: :time
+    attribute :rtc_region, type: :string
+    attribute :video_quality_mode, type: :integer, default: 1
+    attribute :message_count, type: :integer
+    attribute :member_count, type: :integer
+    attribute :thread_metadata, type: :hash
+    attribute :member, type: :hash
+    attribute :default_auto_archive_duration, type: :integer
+    attribute :permissions, type: :string
+    attribute :flags, type: :integer, default: 0
+    attribute :total_message_sent, type: :integer
+    attribute :available_tags, type: :array, default: []
+    attribute :applied_tags, type: :array, default: []
+    attribute :default_reaction_emoji, type: :hash
+    attribute :default_thread_rate_limit_per_user, type: :integer
+    attribute :default_sort_order, type: :integer
+    attribute :default_forum_layout, type: :integer
+
+    # Class-level API client for REST operations
+    class << self
+      attr_accessor :api
+    end
+
+    # Get channel type as symbol
+    # @return [Symbol] Channel type
+    def channel_type
+      TYPES.key(type) || :unknown
+    end
+
+    # Check if this is a text channel
+    # @return [Boolean] True if text channel
+    def text?
+      type == 0 || type == 5
+    end
+
+    # Check if this is a voice channel
+    # @return [Boolean] True if voice channel
+    def voice?
+      type == 2 || type == 13
+    end
+
+    # Check if this is a DM channel
+    # @return [Boolean] True if DM
+    def dm?
+      type == 1
+    end
+
+    # Check if this is a group DM
+    # @return [Boolean] True if group DM
+    def group_dm?
+      type == 3
+    end
+
+    # Check if this is a category
+    # @return [Boolean] True if category
+    def category?
+      type == 4
+    end
+
+    # Check if this is a thread
+    # @return [Boolean] True if thread
+    def thread?
+      type == 10 || type == 11 || type == 12
+    end
+
+    # Check if this is a forum channel
+    # @return [Boolean] True if forum
+    def forum?
+      type == 15
+    end
+
+    # Check if this is a media channel
+    # @return [Boolean] True if media channel
+    def media?
+      type == 16
+    end
+
+    # Check if this is an announcement channel
+    # @return [Boolean] True if announcement
+    def announcement?
+      type == 5
+    end
+
+    # Get mention string for the channel
+    # @return [String] Channel mention
+    def mention
+      "<##{id}>"
+    end
+
+    # Get the jump URL for this channel
+    # @param guild_id [Snowflake, String] Optional guild ID
+    # @return [String] Jump URL
+    def jump_url(guild_id: nil)
+      gid = guild_id || self.guild_id
+      "https://discord.com/channels/#{gid}/#{id}"
+    end
+
+    # Get last message timestamp
+    # @return [Time, nil] Last message time
+    def last_message_at
+      last_message_id&.timestamp
+    end
+
+    # Check if channel is NSFW
+    # @return [Boolean] True if NSFW
+    def nsfw?
+      nsfw
+    end
+
+    # Get the category (parent) ID
+    # @return [Snowflake, nil] Parent category ID
+    def category_id
+      parent_id if category?
+    end
+
+    # Check if this is a stage channel
+    # @return [Boolean] True if stage
+    def stage?
+      type == 13
+    end
+
+    # Get video quality mode name
+    # @return [String] Video quality mode
+    def video_quality_mode_name
+      video_quality_mode == 2 ? 'full' : 'auto'
+    end
+
+    # Get auto archive duration in minutes
+    # @return [Integer, nil] Auto archive duration
+    def auto_archive_duration
+      default_auto_archive_duration
+    end
+
+    # Check if thread is archived
+    # @return [Boolean, nil] True if archived
+    def archived?
+      thread_metadata&.dig('archived')
+    end
+
+    # Get thread archive timestamp
+    # @return [Time, nil] Archive timestamp
+    def archive_timestamp
+      ts = thread_metadata&.dig('archive_timestamp')
+      Time.parse(ts) if ts
+    end
+
+    # Check if thread is locked
+    # @return [Boolean, nil] True if locked
+    def locked?
+      thread_metadata&.dig('locked')
+    end
+
+    # Check if thread is invitable
+    # @return [Boolean, nil] True if invitable
+    def invitable?
+      thread_metadata&.dig('invitable')
+    end
+
+    # Get created_at from snowflake
+    # @return [Time] Channel creation time
+    def created_at
+      id.timestamp
+    end
+
+    # Get permissions as Permission object
+    # @return [Permission, nil] Permissions
+    def permission_overwrites
+      return nil unless permissions
+
+      Permission.new(permissions.to_i)
+    end
+
+    # Check if this is a directory channel
+    # @return [Boolean] True if directory
+    def directory?
+      type == 14
+    end
+
+    # Get slowmode delay in seconds
+    # @return [Integer] Rate limit per user
+    def slowmode_delay
+      rate_limit_per_user || 0
+    end
+
+    # Check if slowmode is enabled
+    # @return [Boolean] True if slowmode enabled
+    def slowmode?
+      rate_limit_per_user.to_i > 0
+    end
+
+    # Check if channel is synced with category permissions
+    # @return [Boolean, nil] True if synced
+    def synced?
+      @raw_data['parent_id'] && @raw_data['permission_overwrites']&.empty?
+    end
+
+    # Get mention string for the channel with type indicator
+    # @return [String] Channel mention with '#' prefix for text channels
+    def mention_with_prefix
+      text? ? "<##{id}>" : mention
+    end
+
+    # Get formatted name with type indicator
+    # @return [String] Formatted name
+    def display_name
+      case type
+      when 0, 5 then "# #{name}"
+      when 2, 13 then "🔊 #{name}"
+      when 4 then "📁 #{name}"
+      else name
+      end
+    end
+
+    # Check if the channel is considered active (has recent messages)
+    # @return [Boolean] True if active
+    def active?
+      return false unless last_message_id
+      last_message_at > Time.now - 86400 # Active within last 24 hours
+    end
+
+    # Get the age of the last message
+    # @return [Float, nil] Seconds since last message
+    def last_message_age
+      return nil unless last_message_at
+      Time.now - last_message_at
+    end
+
+    # Check if this is a news/announcement channel
+    # @return [Boolean] True if news channel
+    def news?
+      type == 5
+    end
+
+    # Get the default auto archive duration in days
+    # @return [Integer] Days
+    def auto_archive_days
+      (default_auto_archive_duration || 4320) / 1440 # Convert minutes to days, default 3 days
+    end
+
+    # Fetch messages from the channel with pagination support
+    # @param limit [Integer] Number of messages (1-100, default 50)
+    # @param before [String, Snowflake] Get messages before this message ID
+    # @param after [String, Snowflake] Get messages after this message ID
+    # @param around [String, Snowflake] Get messages around this message ID (returns 25 before + 25 after)
+    # @return [Array<Message>] Messages
+    def fetch_messages(limit: 50, before: nil, after: nil, around: nil)
+      return [] unless self.class.api
+
+      params = { limit: limit }
+      params[:before] = before.to_s if before
+      params[:after] = after.to_s if after
+      params[:around] = around.to_s if around
+
+      data = self.class.api.get("/channels/#{id}/messages", params: params)
+      data.map { |m| Message.new(m) }
+    end
+
+    # Fetch all messages from the channel with automatic pagination
+    # @param max [Integer] Maximum messages to fetch (nil for all)
+    # @param batch_size [Integer] Messages per request (1-100)
+    # @param direction [Symbol] :backwards (older first) or :forwards (newer first)
+    # @yield [Message] Optional block called for each message
+    # @return [Array<Message>] All fetched messages
+    def fetch_all_messages(max: nil, batch_size: 100, direction: :backwards)
+      return [] unless self.class.api
+
+      messages = []
+      last_id = nil
+
+      loop do
+        batch = if direction == :forwards
+                  fetch_messages(limit: batch_size, after: last_id)
+                else
+                  fetch_messages(limit: batch_size, before: last_id)
+                end
+
+        break if batch.empty?
+
+        batch.each do |message|
+          messages << message
+          yield message if block_given?
+
+          return messages if max && messages.length >= max
+        end
+
+        last_id = direction == :forwards ? batch.last.id : batch.last.id
+
+        # Stop if we got fewer messages than requested (reached the end)
+        break if batch.length < batch_size
+      end
+
+      messages
+    end
+
+    # Create an iterator for fetching messages
+    # @param batch_size [Integer] Messages per request (1-100)
+    # @param direction [Symbol] :backwards (older first) or :forwards (newer first)
+    # @return [MessageIterator] Iterator instance
+    def messages_iterator(batch_size: 100, direction: :backwards)
+      MessageIterator.new(self, batch_size: batch_size, direction: direction)
+    end
+
+    # Search for messages by content (client-side filtering)
+    # Note: Discord API doesn't support server-side message search, this fetches and filters
+    # @param content [String] Content to search for
+    # @param author_id [String] Filter by author ID
+    # @param limit [Integer] Maximum messages to search
+    # @return [Array<Message>] Matching messages
+    def search_messages(content: nil, author_id: nil, limit: 1000)
+      return [] unless self.class.api
+
+      results = []
+
+      fetch_all_messages(max: limit) do |message|
+        next if content && !message.content.to_s.downcase.include?(content.downcase)
+        next if author_id && message.author&.id.to_s != author_id.to_s
+
+        results << message
+      end
+
+      results
+    end
+  end
+
+  # Iterator for paginating through channel messages
+  class MessageIterator
+    include Enumerable
+
+    # @return [Channel] Channel being iterated
+    attr_reader :channel
+
+    # @return [Integer] Messages per batch
+    attr_reader :batch_size
+
+    # @return [Symbol] Direction (:backwards or :forwards)
+    attr_reader :direction
+
+    # Initialize iterator
+    # @param channel [Channel] Channel to iterate
+    # @param batch_size [Integer] Messages per batch
+    # @param direction [Symbol] :backwards (older first) or :forwards (newer first)
+    def initialize(channel, batch_size: 100, direction: :backwards)
+      @channel = channel
+      @batch_size = batch_size
+      @direction = direction
+      @last_id = nil
+      @buffer = []
+      @exhausted = false
+    end
+
+    # Get next message
+    # @return [Message, nil] Next message or nil if exhausted
+    def next
+      fill_buffer if @buffer.empty? && !@exhausted
+
+      @buffer.shift
+    end
+
+    # Check if there are more messages
+    # @return [Boolean] True if more messages available
+    def more?
+      !@exhausted || !@buffer.empty?
+    end
+
+    # Iterate over all messages
+    # @yield [Message]
+    def each
+      return to_enum unless block_given?
+
+      loop do
+        message = self.next
+        break unless message
+
+        yield message
+      end
+    end
+
+    # Reset the iterator
+    # @return [self]
+    def reset
+      @last_id = nil
+      @buffer = []
+      @exhausted = false
+      self
+    end
+
+    private
+
+    def fill_buffer
+      return if @exhausted
+
+      batch = if @direction == :forwards
+                @channel.fetch_messages(limit: @batch_size, after: @last_id)
+              else
+                @channel.fetch_messages(limit: @batch_size, before: @last_id)
+              end
+
+      if batch.empty?
+        @exhausted = true
+      else
+        @buffer = batch
+        @last_id = @direction == :forwards ? batch.last.id : batch.last.id
+        @exhausted = true if batch.length < @batch_size
+      end
+    end
+  end
+end

data/lib/discord_rda/entity/channel_builder.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module DiscordRDA
+  # DSL for building channel modifications.
+  # Provides a fluent interface for modifying channel properties.
+  #
+  class ChannelBuilder
+    # @return [Hash] Channel data being built
+    attr_reader :data
+
+    # Initialize a new channel builder
+    # @param name [String] Channel name
+    def initialize(name = nil)
+      @data = {}
+      @data[:name] = name if name
+    end
+
+    # Set channel name
+    # @param name [String] Channel name (1-100 characters)
+    # @return [self]
+    def name(name)
+      @data[:name] = name
+      self
+    end
+
+    # Set channel type
+    # @param type [Integer, Symbol] Channel type (0=guild_text, 2=guild_voice, etc.)
+    # @return [self]
+    def type(type)
+      @data[:type] = type.is_a?(Symbol) ? Channel::TYPES[type] : type
+      self
+    end
+
+    # Set channel topic
+    # @param topic [String] Channel topic (0-1024 characters for text, 0-4096 for forum)
+    # @return [self]
+    def topic(topic)
+      @data[:topic] = topic
+      self
+    end
+
+    # Set channel bitrate (for voice channels)
+    # @param bitrate [Integer] Bitrate in bits (8000-384000, or 8000-128000 for stage)
+    # @return [self]
+    def bitrate(bitrate)
+      @data[:bitrate] = bitrate
+      self
+    end
+
+    # Set user limit (for voice channels)
+    # @param limit [Integer] User limit (0-99, 0 = unlimited)
+    # @return [self]
+    def user_limit(limit)
+      @data[:user_limit] = limit
+      self
+    end
+
+    # Set rate limit per user (slowmode)
+    # @param seconds [Integer] Seconds between messages (0-21600)
+    # @return [self]
+    def slowmode(seconds)
+      @data[:rate_limit_per_user] = seconds
+      self
+    end
+
+    # Set channel position
+    # @param position [Integer] Position in the left-hand listing
+    # @return [self]
+    def position(position)
+      @data[:position] = position
+      self
+    end
+
+    # Set parent category ID
+    # @param category_id [String, Snowflake] Parent category ID
+    # @return [self]
+    def parent(category_id)
+      @data[:parent_id] = category_id.to_s
+      self
+    end
+
+    # Set NSFW flag
+    # @param nsfw [Boolean] Whether the channel is NSFW
+    # @return [self]
+    def nsfw(nsfw = true)
+      @data[:nsfw] = nsfw
+      self
+    end
+
+    # Set default auto archive duration (for threads)
+    # @param minutes [Integer] Duration in minutes (60, 1440, 4320, 10080)
+    # @return [self]
+    def default_auto_archive_duration(minutes)
+      @data[:default_auto_archive_duration] = minutes
+      self
+    end
+
+    # Set default thread rate limit per user
+    # @param seconds [Integer] Seconds between messages in threads
+    # @return [self]
+    def default_thread_slowmode(seconds)
+      @data[:default_thread_rate_limit_per_user] = seconds
+      self
+    end
+
+    # Set permission overwrites
+    # @param overwrites [Array<Hash>] Permission overwrites array
+    # @return [self]
+    def permission_overwrites(overwrites)
+      @data[:permission_overwrites] = overwrites.map { |o| normalize_overwrite(o) }
+      self
+    end
+
+    # Add a single permission overwrite
+    # @param id [String, Snowflake] Role or user ID
+    # @param type [Integer] 0 for role, 1 for member
+    # @param allow [Integer, String] Allowed permissions bitfield
+    # @param deny [Integer, String] Denied permissions bitfield
+    # @return [self]
+    def add_overwrite(id:, type:, allow: 0, deny: 0)
+      @data[:permission_overwrites] ||= []
+      @data[:permission_overwrites] << {
+        id: id.to_s,
+        type: type,
+        allow: allow.is_a?(Integer) ? allow.to_s : allow,
+        deny: deny.is_a?(Integer) ? deny.to_s : deny
+      }
+      self
+    end
+
+    # Set channel flags
+    # @param flags [Integer] Channel flags bitfield
+    # @return [self]
+    def flags(flags)
+      @data[:flags] = flags
+      self
+    end
+
+    # Set available tags (for forum channels)
+    # @param tags [Array<Hash>] Available tags
+    # @return [self]
+    def available_tags(tags)
+      @data[:available_tags] = tags
+      self
+    end
+
+    # Set default sort order (for forum channels)
+    # @param order [Integer] Default sort order type
+    # @return [self]
+    def default_sort_order(order)
+      @data[:default_sort_order] = order
+      self
+    end
+
+    # Set default forum layout (for forum channels)
+    # @param layout [Integer] Default forum layout view
+    # @return [self]
+    def default_forum_layout(layout)
+      @data[:default_forum_layout] = layout
+      self
+    end
+
+    # Set default reaction emoji (for forum channels)
+    # @param emoji [Hash] Default emoji for forum posts
+    # @return [self]
+    def default_reaction_emoji(emoji)
+      @data[:default_reaction_emoji] = emoji
+      self
+    end
+
+    # Set video quality mode (for voice channels)
+    # @param mode [Integer] Video quality mode (1=auto, 2=full)
+    # @return [self]
+    def video_quality_mode(mode)
+      @data[:video_quality_mode] = mode
+      self
+    end
+
+    # Convert builder to hash
+    # @return [Hash] Channel data hash
+    def to_h
+      @data.dup
+    end
+
+    # Build and return the channel data
+    # @return [Hash] Channel data
+    def build
+      to_h
+    end
+
+    private
+
+    def normalize_overwrite(overwrite)
+      {
+        id: overwrite[:id] || overwrite['id'],
+        type: overwrite[:type] || overwrite['type'],
+        allow: (overwrite[:allow] || overwrite['allow'] || 0).to_s,
+        deny: (overwrite[:deny] || overwrite['deny'] || 0).to_s
+      }
+    end
+  end
+
+  # DSL for creating channel invites
+  class InviteBuilder
+    # @return [Hash] Invite data being built
+    attr_reader :data
+
+    def initialize
+      @data = {}
+    end
+
+    # Set max age in seconds
+    # @param seconds [Integer] Max age (0 = never expires, max 604800)
+    # @return [self]
+    def max_age(seconds)
+      @data[:max_age] = seconds
+      self
+    end
+
+    # Set max uses
+    # @param uses [Integer] Max uses (0 = unlimited, max 100)
+    # @return [self]
+    def max_uses(uses)
+      @data[:max_uses] = uses
+      self
+    end
+
+    # Set temporary membership
+    # @param temporary [Boolean] Whether invite grants temporary membership
+    # @return [self]
+    def temporary(temporary = true)
+      @data[:temporary] = temporary
+      self
+    end
+
+    # Set unique invite
+    # @param unique [Boolean] Whether to create unique URL
+    # @return [self]
+    def unique(unique = true)
+      @data[:unique] = unique
+      self
+    end
+
+    # Set target type
+    # @param type [Integer] Target type (1=stream, 2=embedded_application)
+    # @return [self]
+    def target_type(type)
+      @data[:target_type] = type
+      self
+    end
+
+    # Set target user ID
+    # @param user_id [String, Snowflake] Target user ID
+    # @return [self]
+    def target_user(user_id)
+      @data[:target_user_id] = user_id.to_s
+      self
+    end
+
+    # Set target application ID
+    # @param app_id [String, Snowflake] Target application ID
+    # @return [self]
+    def target_application(app_id)
+      @data[:target_application_id] = app_id.to_s
+      self
+    end
+
+    # Convert to hash
+    # @return [Hash] Invite data
+    def to_h
+      @data.dup
+    end
+
+    # Build and return invite data
+    # @return [Hash] Invite data
+    def build
+      to_h
+    end
+  end
+end