slackblocks 2.5.0

data/lib/slackblocks/generated/style_flags.rb

@@ -0,0 +1,6 @@
+# Generated from spec/model.json. Do not edit by hand.
+module Slackblocks
+  module StyleFlags
+    NAMES = Value.deep_freeze(["bold", "client_highlight", "code", "highlight", "italic", "strike", "unlink"])
+  end
+end

data/lib/slackblocks/generated/vocabulary.rb

@@ -0,0 +1,7 @@
+# Generated from spec/vocabulary.json. Do not edit by hand.
+module Slackblocks
+  module Vocabulary
+    ICON_NAMES = Value.deep_freeze(["archive", "book", "bookmark", "bot", "bug", "calendar", "call", "caret-left", "caret-right", "check", "clipboard", "code", "comment", "compass", "copy", "cube", "download", "edit", "email", "eye-closed", "eye-open", "file", "flag", "folder", "gear", "globe", "heart", "help", "image", "info", "key", "lightbulb", "link", "map", "mobile", "new-window", "pin", "plus", "refine", "refresh", "rocket", "save", "screen", "share", "sparkle", "star", "star-filled", "tag", "thumbs-down", "thumbs-up", "trash", "upload", "user", "warning"])
+    SURFACE_BLOCK_TYPES = Value.deep_freeze({"home" => ["actions", "card", "carousel", "container", "context", "data_table", "data_visualization", "divider", "header", "image", "input", "rich_text", "section", "table", "video"], "message" => ["actions", "card", "carousel", "container", "context", "context_actions", "data_table", "data_visualization", "divider", "file", "header", "image", "input", "markdown", "plan", "rich_text", "section", "table", "task_card", "video"], "modal" => ["actions", "alert", "card", "context", "divider", "header", "image", "input", "rich_text", "section", "video"]})
+  end
+end

data/lib/slackblocks/rich_text_style.rb

@@ -0,0 +1,13 @@
+module Slackblocks
+  class RichTextStyle
+    include Value
+
+    attr_reader(*StyleFlags::NAMES.map(&:to_sym), :additional_fields)
+  end
+  RichTextStyle.const_set(:WIRE_TYPE, "")
+  RichTextStyle.const_set(:FIELD_SPECS, Value.deep_freeze(StyleFlags::NAMES.map do |name|
+    {"name" => name, "wire" => name, "kind" => "boolean", "required" => false}
+  end))
+  RichTextStyle.const_set(:DEFAULTS, Value.deep_freeze({}))
+  RichTextStyle.singleton_class.prepend(KeywordOnly)
+end

data/lib/slackblocks/validation_error.rb

@@ -0,0 +1,18 @@
+module Slackblocks
+  class ValidationError < StandardError
+    CATEGORIES = %w[
+      length-exceeded out-of-range mutually-exclusive
+      type-mismatch missing-required invalid-usage
+    ].freeze
+
+    attr_reader :category, :path
+
+    def initialize(category, path, message)
+      raise ArgumentError, "unknown validation category: #{category}" unless CATEGORIES.include?(category)
+
+      @category = category
+      @path = path
+      super("#{path}: #{message}")
+    end
+  end
+end

data/lib/slackblocks/validator.rb

@@ -0,0 +1,284 @@
+module Slackblocks
+  module Validator
+    def self.validate(klass, values)
+      path = klass.name.split("::").last
+      wire = Value.wire(klass, values)
+      check_limits(wire["text"], "text", "#{path}.text") if klass == PlainText || klass == MarkdownText
+      klass::FIELD_SPECS.each do |field|
+        next if values[field.fetch("name").to_sym].nil?
+
+        check_limits(wire[field.fetch("wire")], field["limits"], "#{path}.#{field.fetch("wire")}")
+      end
+      special(klass, wire, path)
+    end
+
+    def self.limit(key)
+      Limits::VALUES.fetch(key)
+    end
+
+    def self.fail!(category, path, message)
+      Value.fail!(category, path, message)
+    end
+
+    def self.string_limit(value, key, path)
+      return unless value
+
+      fail!("length-exceeded", path, "exceeds #{key}") if value.length > limit(key)
+    end
+
+    def self.text_limit(value, key, path)
+      return unless value
+
+      string_limit(value.fetch("text"), key, path)
+    end
+
+    def self.max_items(items, key, path)
+      return unless items
+
+      fail!("length-exceeded", path, "exceeds #{key}") if items.length > limit(key)
+    end
+
+    def self.special(klass, wire, path)
+      case klass.name.split("::").last
+      when "SlackIcon"
+        unless Vocabulary::ICON_NAMES.include?(wire["name"])
+          fail!("type-mismatch", "#{path}.name", "unknown Slack icon")
+        end
+      when "Attachment"
+        if (color = wire["color"]) && !%w[good warning danger].include?(color) &&
+            !color.match?(/\A#[0-9a-fA-F]{6}\z/)
+          fail!("type-mismatch", "#{path}.color", "expected a six-digit hex color or alias")
+        end
+      when "SectionBlock"
+        fields = wire["fields"] || []
+        fail!("missing-required", path, "expected text or fields") if !wire.key?("text") && fields.empty?
+        fail!("missing-required", "#{path}.fields", "fields cannot be empty") if wire.key?("fields") && fields.empty?
+        fields.each_with_index do |field, index|
+          text_limit(field, "section.fields.item_max_length", "#{path}.fields[#{index}].text")
+        end
+      when "StaticSelectElement", "MultiStaticSelectElement"
+        if wire.key?("options") && wire.key?("option_groups")
+          fail!("mutually-exclusive", path, "options and option_groups cannot both be present")
+        end
+      when "CardBlock"
+        if !%w[hero_image title actions body].any? { |key| wire.key?(key) }
+          fail!("missing-required", path, "card needs content")
+        end
+        if wire.key?("icon") && wire.key?("slack_icon")
+          fail!("mutually-exclusive", path, "icon and slack_icon cannot both be present")
+        end
+      when "ContainerBlock"
+        unless wire.key?("title") || wire.key?("rich_text_title")
+          fail!("missing-required", path, "expected title")
+        end
+        if wire["default_collapsed"] && !wire["is_collapsible"]
+          fail!("invalid-usage", "#{path}.default_collapsed", "requires is_collapsible")
+        end
+        if wire["has_header_divider"] && wire["is_collapsible"]
+          fail!("invalid-usage", "#{path}.has_header_divider", "requires non-collapsible container")
+        end
+      when "ImageBlock", "ImageElement"
+        has_url, has_file = wire.key?("image_url"), wire.key?("slack_file")
+        fail!("missing-required", path, "expected an image source") unless has_url || has_file
+        fail!("mutually-exclusive", path, "expected one image source") if has_url && has_file
+      when "SlackFile"
+        if wire.key?("id") == wire.key?("url")
+          fail!("mutually-exclusive", path, "expected exactly one of id or url")
+        end
+        if wire["id"] && !wire["id"].match?(/\AF[A-Z0-9]{8,}\z/)
+          fail!("type-mismatch", "#{path}.id", "invalid Slack file ID")
+        end
+      when "ConversationFilter"
+        if wire.empty?
+          fail!("missing-required", path, "expected at least one filter field")
+        end
+        (wire["include"] || []).each_with_index do |item, index|
+          unless %w[im mpim private public].include?(item)
+            fail!("type-mismatch", "#{path}.include[#{index}]", "unknown conversation type")
+          end
+        end
+      when "DispatchActionConfiguration"
+        fail!("missing-required", "#{path}.trigger_actions_on", "required") unless wire.key?("trigger_actions_on")
+      when "NumberInputElement"
+        if wire["min_value"] && wire["max_value"] && wire["min_value"] > wire["max_value"]
+          fail!("out-of-range", path, "min_value exceeds max_value")
+        end
+      when "DataTableBlock", "TableBlock"
+        table(wire, path, klass == DataTableBlock)
+      when "AxisConfig"
+        (wire["categories"] || []).each_with_index do |category, index|
+          string_limit(category, "data_visualization.category_label.max_length", "#{path}.categories[#{index}]")
+        end
+        if wire["categories"] && wire["categories"].uniq.length != wire["categories"].length
+          fail!("invalid-usage", "#{path}.categories", "duplicate category")
+        end
+      when "ChartSegment"
+        if wire["value"] <= limit("data_visualization.segment.value.exclusive_min")
+          fail!("out-of-range", "#{path}.value", "expected positive value")
+        end
+      when "LineChart", "BarChart", "AreaChart"
+        chart(wire, path)
+      when "PlanBlock"
+        ids = wire.fetch("tasks").map { |task| task["task_id"] }
+        fail!("invalid-usage", "#{path}.tasks", "duplicate task ID") if ids.uniq.length != ids.length
+      when "MessagePayload", "MessageResponse", "WebhookMessage"
+        message(wire, path)
+      when "ModalView", "HomeTabView"
+        surface(wire.fetch("blocks"), (klass == ModalView) ? "modal" : "home", "#{path}.blocks")
+        if klass == ModalView && !wire.key?("submit") && wire.fetch("blocks").any? { |block| block["type"] == "input" }
+          fail!("missing-required", "#{path}.submit", "required when modal contains an input")
+        end
+      end
+    end
+
+    def self.surface(blocks, name, path)
+      allowed = Vocabulary::SURFACE_BLOCK_TYPES.fetch(name)
+      blocks.each_with_index do |block, index|
+        type = block["type"]
+        fail!("type-mismatch", "#{path}[#{index}].type", "unsupported #{name} block") unless allowed.include?(type)
+        standalone_task(block, "#{path}[#{index}]")
+      end
+    end
+
+    def self.standalone_task(value, path)
+      case value
+      when Hash
+        if value["type"] == "task_card" && value["status"] == "pending"
+          fail!("type-mismatch", "#{path}.status", "pending is plan-only")
+        end
+        value.each do |key, nested|
+          next if key == "tasks" && value["type"] == "plan"
+
+          standalone_task(nested, "#{path}.#{key}")
+        end
+      when Array
+        value.each_with_index { |item, index| standalone_task(item, "#{path}[#{index}]") }
+      end
+    end
+
+    def self.message(wire, path)
+      surface(wire["blocks"] || [], "message", "#{path}.blocks")
+      totals = {"markdown" => 0, "data_table" => 0}
+      tally(wire, totals)
+      if totals["markdown"] > limit("markdown.total_text.max_length")
+        fail!("length-exceeded", path, "message markdown total exceeded")
+      end
+      if totals["data_table"] > limit("data_table.total_content.max_length")
+        fail!("length-exceeded", path, "message data table total exceeded")
+      end
+    end
+
+    def self.tally(node, totals)
+      case node
+      when Hash
+        if node["type"] == "markdown"
+          totals["markdown"] += node.fetch("text").length
+        elsif node["type"] == "data_table"
+          totals["data_table"] += characters(node.fetch("rows"))
+        else
+          node.each_value { |child| tally(child, totals) }
+        end
+      when Array
+        node.each { |child| tally(child, totals) }
+      end
+    end
+
+    def self.characters(node)
+      case node
+      when Array
+        node.sum { |child| characters(child) }
+      when Hash
+        node.sum do |key, child|
+          (key == "text" && child.is_a?(String)) ? child.length : characters(child)
+        end
+      else
+        0
+      end
+    end
+
+    def self.table(wire, path, data_table)
+      rows = wire.fetch("rows")
+      maximum = data_table ? "data_table.columns.max_items" : "table.columns.max_items"
+      rows.each_with_index do |row, index|
+        row_path = "#{path}.rows[#{index}]"
+        max_items(row, maximum, row_path)
+        if data_table
+          fail!("length-exceeded", row_path, "row cannot be empty") if row.empty?
+          if row.length != rows.first.length
+            fail!("invalid-usage", row_path, "data table rows must be rectangular")
+          end
+          row.each_with_index do |cell, column|
+            cell_path = "#{row_path}[#{column}]"
+            if index.zero? && cell["type"] == "rich_text"
+              fail!("type-mismatch", cell_path, "header must be raw")
+            end
+            if %w[raw_text raw_number].include?(cell["type"]) && cell.fetch("text").empty?
+              fail!("length-exceeded", "#{cell_path}.text", "empty cell")
+            end
+          end
+        end
+      end
+      if data_table
+        fail!("invalid-usage", "#{path}.column_settings", "unsupported") if wire.key?("column_settings")
+        if characters(rows) > limit("data_table.content.max_length")
+          fail!("length-exceeded", "#{path}.rows", "table content exceeded")
+        end
+      end
+    end
+
+    def self.chart(wire, path)
+      axis = wire.fetch("axis_config").fetch("categories")
+      # @type var names: Array[String]
+      names = []
+      wire.fetch("series").each_with_index do |series, index|
+        item_path = "#{path}.series[#{index}]"
+        names << series["name"]
+        labels = series.fetch("data").map { |point| point["label"] }
+        unless labels.length == axis.length && labels.sort == axis.sort
+          fail!("invalid-usage", "#{item_path}.data", "points must cover every category exactly once")
+        end
+      end
+      fail!("invalid-usage", "#{path}.series", "duplicate series name") if names.uniq.length != names.length
+    end
+
+    def self.check_limits(value, prefix, path)
+      return unless prefix
+
+      limits = Limits::VALUES
+      length = if value.is_a?(String)
+        value.length
+      elsif value.is_a?(Array)
+        value.length
+      elsif value.is_a?(Hash) && value["text"].is_a?(String)
+        value["text"].length
+      end
+      suffixes = value.is_a?(Array) ? %w[min_items max_items] : %w[min_length max_length]
+      if length
+        suffixes.each do |suffix|
+          bound = limits["#{prefix}.#{suffix}"]
+          next unless bound
+
+          if suffix.start_with?("min") && length < bound
+            fail!("length-exceeded", path, "expected at least #{bound}")
+          elsif suffix.start_with?("max") && length > bound
+            fail!("length-exceeded", path, "expected at most #{bound}")
+          end
+        end
+      end
+      if value.is_a?(Numeric)
+        %w[min max exclusive_min exclusive_max].each do |suffix|
+          bound = limits["#{prefix}.#{suffix}"]
+          next unless bound
+
+          invalid = case suffix
+          when "min" then value < bound
+          when "max" then value > bound
+          when "exclusive_min" then value <= bound
+          when "exclusive_max" then value >= bound
+          end
+          fail!("out-of-range", path, "outside #{suffix} #{bound}") if invalid
+        end
+      end
+    end
+  end
+end

data/lib/slackblocks/value.rb

@@ -0,0 +1,274 @@
+require "json"
+
+module Slackblocks
+  module KeywordOnly
+    def new(*args, **keywords)
+      raise ArgumentError, "use keyword arguments" unless args.empty?
+
+      super(**keywords)
+    end
+
+    def [](*args, **keywords)
+      new(*args, **keywords)
+    end
+  end
+
+  module Value
+    def self.deep_freeze(value)
+      case value
+      when String
+        value.freeze
+      when Array
+        value.each { |item| deep_freeze(item) }
+        value.freeze
+      when Hash
+        value.each { |key, item|
+          deep_freeze(key)
+          deep_freeze(item)
+        }
+        value.freeze
+      else
+        value
+      end
+    end
+
+    def self.fail!(category, path, message)
+      raise ValidationError.new(category, path, message)
+    end
+
+    def self.string(value, path)
+      fail!("type-mismatch", path, "expected a String") unless value.is_a?(String)
+      fail!("type-mismatch", path, "invalid string encoding") unless value.valid_encoding?
+
+      value.encode(Encoding::UTF_8).freeze
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      fail!("type-mismatch", path, "cannot transcode to UTF-8")
+    end
+
+    def self.json_value(value, path, seen = {})
+      case value
+      when nil, true, false, Integer
+        value
+      when String
+        string(value, path)
+      when Float
+        fail!("out-of-range", path, "number must be finite") unless value.finite?
+
+        value
+      when Value
+        value
+      when Array
+        fail!("type-mismatch", path, "cyclic array") if seen[value.object_id]
+
+        seen[value.object_id] = true
+        copy = value.each_with_index.map { |item, index| json_value(item, "#{path}[#{index}]", seen) }.freeze
+        seen.delete(value.object_id)
+        copy
+      when Hash
+        fail!("type-mismatch", path, "cyclic map") if seen[value.object_id]
+
+        seen[value.object_id] = true
+        # @type var copy: Hash[String, untyped]
+        copy = {}
+        value.each do |key, item|
+          fail!("type-mismatch", path, "map key must be a string or symbol") unless key.is_a?(String) || key.is_a?(Symbol)
+
+          normalized = string(key.to_s, path)
+          fail!("invalid-usage", "#{path}.#{normalized}", "duplicate key") if copy.key?(normalized)
+
+          copy[normalized] = json_value(item, "#{path}.#{normalized}", seen)
+        end
+        seen.delete(value.object_id)
+        copy.freeze
+      else
+        fail!("type-mismatch", path, "value cannot be represented as JSON")
+      end
+    end
+
+    def self.normalize_field(field, value, path)
+      kind = field.fetch("kind")
+      target = field["target"] && Slackblocks.const_get(field["target"], false)
+      case kind
+      when "string"
+        string(value, path)
+      when "boolean"
+        fail!("type-mismatch", path, "expected a boolean") unless value == true || value == false
+
+        value
+      when "int", "long"
+        fail!("type-mismatch", path, "expected an Integer") unless value.is_a?(Integer)
+
+        value
+      when "double", "number"
+        fail!("type-mismatch", path, "expected an Integer or Float") unless value.is_a?(Integer) || value.instance_of?(Float)
+        fail!("out-of-range", path, "number must be finite") if value.is_a?(Float) && !value.finite?
+
+        value
+      when "enum"
+        allowed = target.constants(false).map { |name| target.const_get(name, false) }
+        fail!("type-mismatch", path, "unknown enum value") unless value.is_a?(Symbol) && allowed.include?(value)
+
+        value
+      when "map"
+        fail!("type-mismatch", path, "expected a Hash") unless value.is_a?(Hash)
+
+        json_value(value, path)
+      when "style"
+        fail!("type-mismatch", path, "expected RichTextStyle") unless value.is_a?(RichTextStyle)
+
+        used = value.to_h.select { |name, flag| name != :additional_fields && !flag.nil? }.keys.map(&:to_s) + value.additional_fields.keys
+        fail!("type-mismatch", path, "unsupported style flag") unless (used - field.fetch("flags")).empty?
+
+        value
+      when "object"
+        fail!("type-mismatch", path, "expected #{target}") unless value.is_a?(target)
+
+        value
+      when "text"
+        return Slackblocks.const_get((field["coerce"] == "plain_text") ? "PlainText" : "MarkdownText", false).new(text: value) if value.is_a?(String)
+
+        fail!("type-mismatch", path, "expected text") unless value.is_a?(target)
+
+        value
+      when "list", "rows", "textList", "stringList"
+        fail!("type-mismatch", path, "expected an Array") unless value.is_a?(Array)
+
+        value.each_with_index.map do |item, index|
+          item_path = "#{path}[#{index}]"
+          if kind == "rows"
+            fail!("type-mismatch", item_path, "expected a row Array") unless item.is_a?(Array)
+
+            item.each_with_index.map do |cell, column|
+              fail!("type-mismatch", "#{item_path}[#{column}]", "wrong cell type") unless cell.is_a?(target)
+
+              cell
+            end.freeze
+          elsif kind == "textList"
+            normalize_field({"kind" => "text", "target" => field["target"], "coerce" => field["coerce"]}, item, item_path)
+          elsif kind == "stringList"
+            string(item, item_path)
+          else
+            fail!("type-mismatch", item_path, "wrong item type") unless item.is_a?(target)
+
+            item
+          end
+        end.freeze
+      else
+        raise "unhandled model field kind: #{kind}"
+      end
+    end
+
+    def self.construct(klass, keywords)
+      fields = klass::FIELD_SPECS
+      names = fields.map { |field| field.fetch("name").to_sym }
+      unknown = keywords.keys - names - [:additional_fields]
+      raise ArgumentError, "unknown keywords: #{unknown.inspect}" unless unknown.empty?
+
+      # @type var values: Hash[Symbol, untyped]
+      values = {}
+      fields.each do |field|
+        name = field.fetch("name")
+        symbol = name.to_sym
+        path = "#{klass.name.split("::").last}.#{field.fetch("wire")}"
+        value = if keywords.key?(symbol)
+          keywords[symbol]
+        else
+          default = klass::DEFAULTS.fetch(name, nil)
+          (field["kind"] == "enum" && default) ? default.to_sym : default
+        end
+        if value.nil?
+          fail!("missing-required", path, "required field is missing") if field["required"]
+          values[symbol] = nil
+        else
+          values[symbol] = normalize_field(field, value, path)
+        end
+      end
+      raw_extra = keywords.fetch(:additional_fields, nil)
+      if raw_extra.nil?
+        values[:additional_fields] = deep_freeze({})
+      else
+        fail!("type-mismatch", "#{klass.name}.additional_fields", "expected a Hash") unless raw_extra.is_a?(Hash)
+
+        normalized = json_value(raw_extra, "#{klass.name}.additional_fields")
+        reserved = fields.map { |field| field.fetch("wire") } + ["type"]
+        normalized.each_key do |key|
+          fail!("invalid-usage", "#{klass.name}.#{key}", "field is reserved") if key.empty? || reserved.include?(key)
+        end
+        values[:additional_fields] = normalized
+      end
+      Validator.validate(klass, values)
+      values
+    end
+
+    def self.detach(value)
+      case value
+      when Value
+        value.as_json
+      when Array
+        value.map { |item| detach(item) }
+      when Hash
+        value.to_h { |key, item| [key.dup, detach(item)] }
+      when String
+        value.dup
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+
+    def self.wire(klass, values)
+      # @type var wire: Hash[String, untyped]
+      wire = {}
+      wire["type"] = klass::WIRE_TYPE.dup unless klass::WIRE_TYPE.empty?
+      klass::FIELD_SPECS.each do |field|
+        value = values[field.fetch("name").to_sym]
+        wire[field.fetch("wire").dup] = detach(value) unless value.nil?
+      end
+      values.fetch(:additional_fields).each { |key, value| wire[key.dup] = detach(value) }
+      if klass.name == "Slackblocks::PlanBlock" && wire.key?("tasks")
+        wire["tasks"].each { |task| task.delete("type") }
+      elsif klass.name == "Slackblocks::Attachment" && wire["color"].is_a?(String)
+        color = wire["color"]
+        wire["color"] = "##{color}" if color.match?(/\A[0-9a-fA-F]{6}\z/)
+      end
+      wire
+    end
+
+    def initialize(**keywords)
+      Value.construct(self.class, keywords).each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+      freeze
+    end
+
+    def to_h
+      self.class.const_get(:FIELD_SPECS).to_h do |field|
+        name = field.fetch("name").to_sym
+        [name, public_send(name)]
+      end.merge(additional_fields: additional_fields)
+    end
+
+    def with(**changes)
+      changes.empty? ? self : self.class.public_send(:new, **to_h.merge(changes))
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && to_h == other.to_h
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    def as_json(_options = nil)
+      Value.wire(self.class, to_h)
+    end
+
+    def to_json(options = nil)
+      options.nil? ? JSON.generate(as_json) : JSON.generate(as_json, options)
+    end
+  end
+end

data/lib/slackblocks/version.rb

@@ -0,0 +1,4 @@
+module Slackblocks
+  VERSION = "2.5.0"
+  SPEC_VERSION = "1.2.0"
+end

data/lib/slackblocks.rb

@@ -0,0 +1,11 @@
+require "json"
+require_relative "slackblocks/version"
+require_relative "slackblocks/validation_error"
+require_relative "slackblocks/value"
+require_relative "slackblocks/validator"
+require_relative "slackblocks/generated/style_flags"
+require_relative "slackblocks/rich_text_style"
+require_relative "slackblocks/generated/limits"
+require_relative "slackblocks/generated/vocabulary"
+require_relative "slackblocks/generated/models"
+require_relative "slackblocks/components"