@spec default_capabilities() :: t()

Returns the default capabilities that all channels should have.

@spec empty() :: t()

Returns an empty capabilities map.

@spec fallback_for(t(), LemonChannels.Capabilities.Capability.type()) ::
  {:ok, term()} | {:error, :no_fallback}

Returns suggested fallback options for unsupported capabilities.

Examples

caps = Capabilities.new([:threads])  # no rich_blocks
Capabilities.fallback_for(caps, :rich_blocks)
# => {:text, "Fallback to plain text representation"}

@spec from_legacy(map()) :: t()

Converts legacy capability format to new format.

@spec get(t(), LemonChannels.Capabilities.Capability.type()) ::
  LemonChannels.Capabilities.Capability.t() | nil

Gets a capability by type.

Examples

caps = Capabilities.new([{:attachments, max_size: 10_000_000}])
Capabilities.get(caps, :attachments)
# => %Capability{type: :attachments, enabled: true, config: %{max_size: 10000000}}

@spec list(t()) :: [LemonChannels.Capabilities.Capability.type()]

Returns a list of all supported capability types.

@spec merge(t(), t()) :: t()

Merges two capabilities maps. The second map takes precedence.

Examples

base = Capabilities.new([:threads, {:attachments, max_size: 5_000_000}])
override = Capabilities.new([{:attachments, max_size: 10_000_000}, :streaming])
Capabilities.merge(base, override)
# => %{attachments: %{max_size: 10000000}, threads: %{...}, streaming: %{...}}

@spec new([LemonChannels.Capabilities.Capability.spec()]) :: t()

Creates a new capabilities map from a list of capability specs.

Examples

# Simple boolean capabilities
Capabilities.new([:threads, :reactions, :streaming])

# Capabilities with configuration
Capabilities.new([
  :threads,
  {:attachments, max_size: 10_000_000},
  {:rich_blocks, [:markdown, :buttons, :sections]}
])

@spec set(atom()) :: [LemonChannels.Capabilities.Capability.t()]

Creates a capability set for common channel types.

Predefined Sets

• :messaging - Basic messaging (threads, reactions, edit, delete)
• :rich_content - Rich content support (attachments, rich_blocks)
• :realtime - Real-time features (streaming, voice)
• :full - All capabilities

Examples

Capabilities.set(:messaging)
# => [%Capability{type: :threads}, %Capability{type: :reactions}, ...]

@spec supports?(t(), LemonChannels.Capabilities.Capability.type()) :: boolean()

Checks if a capability is supported.

Examples

caps = Capabilities.new([:threads, :reactions])
Capabilities.supports?(caps, :threads)
# => true
Capabilities.supports?(caps, :streaming)
# => false

@spec supports_feature?(t(), LemonChannels.Capabilities.Capability.type(), atom()) ::
  boolean()

Checks if a capability supports specific features.

Examples

caps = Capabilities.new([{:rich_blocks, [:markdown, :buttons]}])
Capabilities.supports_feature?(caps, :rich_blocks, :markdown)
# => true
Capabilities.supports_feature?(caps, :rich_blocks, :tables)
# => false

@spec to_legacy(t()) :: map()

Converts new capability format to legacy format.

This is a temporary function for migration purposes.

@spec validate(t(), LemonChannels.Capabilities.Capability.type(), map()) ::
  :ok | {:error, term()}

Validates a capability request against the supported capabilities.

Returns :ok if valid, or {:error, reason} if invalid.

Examples

caps = Capabilities.new([{:attachments, max_size: 10_000_000}])
Capabilities.validate(caps, :attachments, %{size: 5_000_000, mime_type: "image/png"})
# => :ok

Capabilities.validate(caps, :attachments, %{size: 15_000_000, mime_type: "image/png"})
# => {:error, :file_too_large}