calmlens 0.1.1 → 0.18.0

data/lib/calmlens/text.rb

@@ -12,16 +12,18 @@ module CalmLens
     # Moderates a string as a `text/plain` asset and waits for the decision.
     # @option options [String] :text
     # @option options [String] :name defaults to `text`
-    # @return [Hash] the asset; publish only when `moderation.status` is `approved` and
-    #   `moderation.action` is nil.
-    def moderate(options)
+    # @option options [String] :author_id who wrote the text, as for {Assets#create}
+    # @option options [Hash] :context earlier posts in the conversation, as for {Assets#create}
+    # @return [Hash] the asset; show it to everyone only when `classification.moderation.status` is
+    #   `allowed` or `limited` (reduce the reach of `limited` content).
+    def classify(options)
       api, request = call(options) { |*split| split }
       text = api['text']
       unless text.is_a?(String) && !text.strip.empty?
-        raise Internal.invalid('Text to moderate must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+        raise Internal.invalid('Text to classify must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
       end
 
-      @assets.moderate(without(api, 'text').merge('name' => api.fetch('name', 'text'),
+      @assets.classify(without(api, 'text').merge('name' => api.fetch('name', 'text'),
                                                   'content' => { 'plainText' => text, 'type' => 'text/plain' },
                                                   'request_options' => request))
     end

data/lib/calmlens/transforms.rb

@@ -6,7 +6,13 @@ module CalmLens
   module Transforms
     module_function
 
-    TYPE = /\A[A-Za-z0-9_]+\z/
+    OPTION_NAME = /\A[a-z][a-zA-Z0-9]*\z/
+    # <generated: image-transform-colours>
+    # Generated by packages/sdk-contract/generate.ts from IMAGE_TRANSFORM_OPTIONS_SCHEMA; do not edit.
+    # Options that hold colours, written as hex without `#` in a selector.
+    COLOUR_KEYS = %w[background border.color trim.border.color].freeze
+    # </generated: image-transform-colours>
+    HEX_COLOUR = /\A#((?:\h{3}){1,2}|(?:\h{4}){1,2})\z/
 
     # Returns the selector the API and CDN accept for a transform: a selector String unchanged, or
     # structured steps (`{type:, options:}` or an Array of them) serialized by {serialize}.
@@ -14,21 +20,21 @@ module CalmLens
       value.nil? || value.is_a?(String) ? value : serialize(value)
     end
 
-    # Builds the CDN path of a transform. A selector String keeps its own separators and literal
-    # `[`/`]`, which the CDN matches; serialized steps are already path-safe.
+    # Builds the CDN path of a transform. A selector String keeps its own step separators and is
+    # encoded like JavaScript's encodeURI; serialized steps are already path-safe.
     def path(value)
       return serialize(value) unless value.is_a?(String)
 
       text = value.sub(%r{\A/+}, '')
       raise Internal.invalid('Transform cannot contain "..", "?" or "#"') if text.include?('..') || text.match?(/[?#]/)
 
-      # Like JavaScript's encodeURI, except that brackets stay literal.
-      text.b.gsub(%r{[^A-Za-z0-9\-_.!~*'();/:@&=+$,\[\]]}n) { |byte| format('%%%02X', byte.ord) }
+      # Like JavaScript's encodeURI.
+      text.b.gsub(%r{[^A-Za-z0-9\-_.!~*'();/:@&=+$,]}n) { |byte| format('%%%02X', byte.ord) }
     end
 
-    # Serializes structured transforms as a CDN selector such as `imageTransform[format=png,width=1024]`.
-    # Option keys are sorted so equal transforms share a URL; nested keys (`border[color]`) and values
-    # are percent-encoded.
+    # Serializes structured transforms as a CDN selector, one path segment per step, such as
+    # `fit=cover,width=640/format=webp`. Option keys are sorted so equal transforms share a URL, nested
+    # keys are dotted (`border.color`), hex colours are written without `#` and values are percent-encoded.
     def serialize(value)
       steps = value.is_a?(Array) ? value : [value]
       raise Internal.invalid('Transform needs at least one step') if steps.empty?
@@ -37,35 +43,48 @@ module CalmLens
         raise Internal.invalid('Transform steps must be Hashes') unless step.is_a?(Hash)
 
         step = step.transform_keys(&:to_s)
-        type = step['type']
-        unless type.is_a?(String) && type.match?(TYPE)
-          raise Internal.invalid('Transform type must contain only letters, digits and underscores')
-        end
+        raise Internal.invalid('Transform type must be "imageTransform"') unless step['type'] == 'imageTransform'
 
         options = step['options'] || {}
         raise Internal.invalid('Transform options must be a Hash') unless options.is_a?(Hash)
 
         pairs = []
         sorted_options(options).each { |key, item| append_pairs(pairs, key, item) }
-        "#{type}[#{pairs.join(',')}]"
-      end.join(',')
+        raise Internal.invalid('Transform steps need at least one option') if pairs.empty?
+
+        pairs.join(',')
+      end.join('/')
     end
 
-    def sorted_options(options) = options.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+    def sorted_options(options, prefix = '')
+      options.map do |key, item|
+        name = key.to_s
+        raise Internal.invalid("Transform option \"#{prefix}#{name}\" is not a valid name") unless name.match?(OPTION_NAME)
+
+        [name, item]
+      end.sort_by(&:first)
+    end
 
     def append_pairs(pairs, key, value)
       return if value.nil?
-      return sorted_options(value).each { |child, item| append_pairs(pairs, "#{key}[#{child}]", item) } if value.is_a?(Hash)
+      return sorted_options(value, "#{key}.").each { |child, item| append_pairs(pairs, "#{key}.#{child}", item) } if value.is_a?(Hash)
 
       text = case value
-             when String, true, false, Integer then value.to_s
+             when String then colour(key, value)
+             when true, false, Integer then value.to_s
              when Float
                raise Internal.invalid("Transform option \"#{key}\" must be a finite number") unless value.finite?
 
                js_number(value)
              else raise Internal.invalid("Transform option \"#{key}\" must be a String, number, boolean or Hash")
              end
-      pairs << "#{component(key)}=#{component(text)}"
+      pairs << "#{key}=#{component(text)}"
+    end
+
+    # Writes a hex colour option without `#`, in lower case; other values are unchanged.
+    def colour(key, value)
+      match = COLOUR_KEYS.include?(key) && HEX_COLOUR.match(value)
+      match ? match[1].downcase : value
     end
 
     # Percent-encodes everything except RFC 3986 unreserved characters.

data/lib/calmlens/upload_body.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module CalmLens
-  # An upload payload: a binary String, or an IO streamed with an exact byte count.
+  # An upload payload: a binary String, or an IO streamed with an exact byte count (or, when its
+  # length is unknown, until it ends, sent with chunked transfer encoding).
   # @api private
   class UploadBody
     PAYLOAD_KEYS = %w[plainText base64 data bytes].freeze
@@ -11,7 +12,8 @@ module CalmLens
 
     # Builds the body from upload content options (`plainText`, `base64`, or `data`/`bytes` as a
     # String or IO). IO input is streamed, never read into memory.
-    def self.from(content, multipart:)
+    # @param part_size [Boolean] check that a multipart part other than the last has 5 MiB.
+    def self.from(content, multipart:, part_size: true)
       raise Internal.invalid('Upload content must be a Hash', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless content.is_a?(Hash)
 
       keys = PAYLOAD_KEYS.select { |key| content.key?(key) }
@@ -21,7 +23,7 @@ module CalmLens
       if content.key?('sizeInBytes') && content['sizeInBytes'] != body.size
         raise Internal.invalid('sizeInBytes must match the payload byte length', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
       end
-      if multipart && !content.fetch('isFinal', false) && body.size < MIN_PART_BYTES
+      if part_size && multipart && !content.fetch('isFinal', false) && body.size && body.size < MIN_PART_BYTES
         raise Internal.invalid('Multipart upload parts must be at least 5MiB except the final part.',
                                ErrorCodes::INVALID_UPLOAD_PAYLOAD)
       end
@@ -56,16 +58,15 @@ module CalmLens
       raise Internal.invalid('Invalid base64', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
     end
 
-    # The bytes left in a sized stream (a File, Tempfile or StringIO), or the declared size.
+    # The bytes left in a sized stream (a File, Tempfile or StringIO), the declared size, or nil when
+    # the length is unknown (a pipe or socket).
     def self.stream_size(io, declared)
       return declared if declared.is_a?(Integer) && declared >= 0
 
       remaining = io.size - io.pos if io.respond_to?(:size) && io.respond_to?(:pos)
-      return remaining if remaining.is_a?(Integer) && remaining >= 0
-
-      raise Internal.invalid('Pass sizeInBytes for a stream whose length is unknown', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      remaining.is_a?(Integer) && remaining >= 0 ? remaining : nil
     rescue IOError, SystemCallError, NoMethodError
-      raise Internal.invalid('Pass sizeInBytes for a stream whose length is unknown', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      nil
     end
     private_class_method :build, :decode64, :stream_size
 
@@ -97,7 +98,8 @@ module CalmLens
       @source.read || ''.b
     end
 
-    # Reads exactly `size` bytes from an IO and fails if it holds fewer or more.
+    # Reads exactly `size` bytes from an IO and fails if it holds fewer or more; without a size, reads
+    # until the IO ends.
     class IOReader
       attr_reader :size
 
@@ -119,6 +121,7 @@ module CalmLens
 
       def read(length = nil, buffer = nil)
         return (buffer ? buffer.replace(''.b) : ''.b) if length&.zero?
+        return read_unsized(length, buffer) if @size.nil?
 
         if @remaining.zero?
           extra = @io.read(1)
@@ -140,6 +143,14 @@ module CalmLens
         buffer ? buffer.replace(chunk) : chunk
       end
 
+      def read_unsized(length, buffer)
+        chunk = @io.read(*[length].compact)
+        return buffer&.clear && nil if chunk.nil? || (length && chunk.empty?)
+
+        chunk = chunk.b
+        buffer ? buffer.replace(chunk) : chunk
+      end
+
       def readpartial(length, buffer = nil)
         read(length, buffer) || raise(EOFError)
       end

data/lib/calmlens/upload_tokens.rb

@@ -26,7 +26,14 @@ module CalmLens
     # @option options [Integer] :expires_in_seconds lifetime, 1 to 3600 (default 600)
     # @return [Hash] `{'token' => String, 'expiresAt' => Integer}` (milliseconds since the Unix epoch)
     def sign(options)
-      api, = call(options) { |*split| split }
+      call(options) { UploadTokens.sign_at(@api_key, options, now: (Time.now.to_f * 1000).to_i, nonce: SecureRandom.uuid) }
+    end
+
+    # Signs like {#sign} at a fixed time with a fixed nonce. {MockServerClient.sign_upload_token}
+    # exposes it to tests that need exact tokens.
+    # @api private
+    def self.sign_at(api_key, options, now:, nonce:)
+      api, = Internal.options(options)
       preset_id = api['uploadPresetId']
       Internal.segment(preset_id)
       ttl = api.fetch('expiresInSeconds', DEFAULT_TTL_SECONDS)
@@ -39,12 +46,13 @@ module CalmLens
         raise Internal.invalid('externalId must be a non-empty string')
       end
 
-      expires_at = (Time.now.to_f * 1000).to_i + (ttl * 1000)
-      claims = { 'v' => 1, 'u' => preset_id, 'k' => @api_key[0, @api_key.start_with?('clsk_') ? 13 : 8],
-                 'e' => expires_at, 'n' => SecureRandom.uuid }
+      expires_at = now + (ttl * 1000)
+      claims = { 'v' => 1, 'u' => preset_id, 'k' => api_key[0, api_key.start_with?('clsk_') ? 13 : 8],
+                 'e' => expires_at, 'n' => nonce }
       claims['x'] = external_id if external_id
-      body = [JSON.generate(claims)].pack('m0').tr('+/', '-_').delete('=')
-      secret = Digest::SHA256.hexdigest(@api_key)
+      # Written as JavaScript's JSON.stringify writes it: raw UTF-8, `/` and `<>&` unescaped.
+      body = [JSON.generate(claims, script_safe: false, ascii_only: false)].pack('m0').tr('+/', '-_').delete('=')
+      secret = Digest::SHA256.hexdigest(api_key)
       signature = OpenSSL::HMAC.hexdigest('SHA256', secret, SIGNING_CONTEXT + body)
       { 'token' => "#{TOKEN_PREFIX}#{body}.#{signature}", 'expiresAt' => expires_at }
     end

data/lib/calmlens/version.rb

@@ -2,5 +2,5 @@
 
 module CalmLens
   # The gem version. The gemspec and the User-Agent header read it from here.
-  VERSION = '0.1.1'
+  VERSION = '0.18.0'
 end

data/lib/calmlens/webhooks.rb

@@ -14,23 +14,28 @@ module CalmLens
   # Deliveries whose timestamp is further than this from the receiver's clock are rejected.
   WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300
 
-  # A verified webhook delivery: `{id, type, createdAt, projectId, data}`, where `data` holds the
-  # event's `severity`, `title`, `description`, `assetId`, `asset` and `facts`.
+  # A verified webhook delivery. The body has the shape of an {Events#list} item:
+  # `{id, projectId, type, severity, title, description, assetId, asset, facts, createdAt}`.
+  # Fields CalmLens adds later are kept in {#payload}, as are unknown asset and fact fields.
   #
   # @!attribute id [String] the event ID.
-  # @!attribute type [String] such as `asset.approved`. New types may appear: ignore unknown ones.
-  # @!attribute created_at [Integer] milliseconds since the epoch.
   # @!attribute project_id [String]
-  # @!attribute data [Hash{String => Object}] the event fields, with the API's camelCase keys.
-  WebhookEvent = Struct.new(:id, :type, :created_at, :project_id, :data, keyword_init: true) do
-    # @return [String, nil]
-    def asset_id = data['assetId']
-
-    # @return [Array<Hash>] `{'key', 'value', 'url'?}` entries registered for the event type.
-    def facts = data['facts'].is_a?(Array) ? data['facts'] : []
-
+  # @!attribute type [String] such as `asset.allowed`. New types may appear: ignore unknown ones.
+  # @!attribute severity [String, nil] `low` or `high`.
+  # @!attribute title [String, nil]
+  # @!attribute description [String, nil]
+  # @!attribute asset_id [String, nil]
+  # @!attribute asset [Hash, nil] the asset's status when the event was created.
+  # @!attribute facts [Array<Hash>] `{'key', 'value', 'url'?}` entries registered for the event type.
+  # @!attribute created_at [Integer] milliseconds since the epoch.
+  # @!attribute payload [Hash{String => Object}] the delivery body as received, with every field.
+  WebhookEvent = Struct.new(:id, :project_id, :type, :severity, :title, :description, :asset_id, :asset, :facts,
+                            :created_at, :payload, keyword_init: true) do
     # @return [Boolean] true for a test send from the portal or CLI.
-    def test? = facts.any? { |fact| fact.is_a?(Hash) && fact['key'] == 'test' && fact['value'] == true }
+    def test? = Webhooks.test_event?(self)
+
+    # @return [Hash{String => Object}] the delivery body as received, with every field.
+    def to_payload = payload
   end
 
   # Webhook signing and verification. Always verify the exact bytes received: read the raw body
@@ -50,37 +55,88 @@ module CalmLens
       "v1=#{OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp.to_s.b}.".b + raw)}"
     end
 
-    # Checks a delivery's signature and freshness in constant time.
+    # The headers of one signed delivery of a body, as CalmLens sends them, to test a receiver.
+    # @param payload [String] the raw body
+    # @param delivery_id [String] the `x-calmlens-delivery` value
+    # @param secret [String]
+    # @param timestamp [Integer] Unix seconds
+    # @return [Hash{String => String}]
+    def headers(payload:, delivery_id:, secret:, timestamp: Time.now.to_i)
+      {
+        'content-type' => 'application/json',
+        WEBHOOK_DELIVERY_HEADER => delivery_id.to_s,
+        WEBHOOK_TIMESTAMP_HEADER => timestamp.to_s,
+        WEBHOOK_SIGNATURE_HEADER => signature_header(payload: payload, timestamp: timestamp, secret: secret)
+      }
+    end
+
+    # Whether an event is a test send from the portal or the CLI rather than a real event: its
+    # `facts` hold the registered `{ key: "test", value: true }` fact.
+    # @param event [WebhookEvent, Hash] a parsed delivery, or a delivery body with string keys
+    # @return [Boolean]
+    def test_event?(event)
+      facts = event.is_a?(Hash) ? event['facts'] : event.facts
+      facts.is_a?(Array) && facts.any? { |fact| fact.is_a?(Hash) && fact['key'] == 'test' && fact['value'] == true }
+    end
+
+    # Converts an event from {Events#list} to the JSON body of its webhook delivery, which has the
+    # same fields: `description`, `assetId` and `asset` are nil when absent.
+    # @param event [Hash] an event with string keys, as {Events#list} returns it
+    # @return [Hash] `{ 'id', 'projectId', 'type', 'severity', 'title', 'description', 'assetId', 'asset', 'facts', 'createdAt' }`
+    def to_payload(event)
+      raise Internal.invalid('event must be a Hash') unless event.is_a?(Hash)
+
+      { 'id' => event['id'], 'projectId' => event['projectId'], 'type' => event['type'], 'severity' => event['severity'],
+        'title' => event['title'], 'description' => event['description'], 'assetId' => event['assetId'],
+        'asset' => event['asset'], 'facts' => event['facts'], 'createdAt' => event['createdAt'] }
+    end
+
+    # Checks a delivery's signature and freshness in constant time. Pass the `signature` and
+    # `timestamp` header values, or the request's `headers` to read them from.
     # @param payload [String] the raw request body, exactly as received
     # @param signature [String, nil] the `x-calmlens-signature` header
     # @param timestamp [String, nil] the `x-calmlens-timestamp` header
+    # @param headers [Hash, #to_hash, nil] request headers, as a Hash whose names may have any case
+    #   and whose values are Strings or Arrays of repeated values (`Net::HTTPHeader#to_hash`), or a
+    #   Rack env (`HTTP_X_CALMLENS_SIGNATURE`). Repeated values are joined with `,`.
     # @param secret [String] the webhook's signing secret
     # @param tolerance_seconds [Integer]
     # @param now [Integer] Unix seconds
     # @return [Boolean]
     # @raise [InvalidArgumentError] when payload is not a String, such as an already parsed Hash.
-    def verify(payload:, signature:, timestamp:, secret:, tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
-               now: Time.now.to_i)
+    def verify(payload:, secret:, signature: nil, timestamp: nil, headers: nil,
+               tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, now: Time.now.to_i)
       raw = raw_body(payload)
+      signature = header(headers, WEBHOOK_SIGNATURE_HEADER) if signature.nil?
+      timestamp = header(headers, WEBHOOK_TIMESTAMP_HEADER) if timestamp.nil?
       stamp = timestamp.to_s.strip
       return false if !secret.is_a?(String) || secret.empty? || signature.to_s.empty? || !stamp.match?(/\A[0-9]+\z/)
-      return false if (now.floor - stamp.to_i).abs > tolerance_seconds
+      return false if (now.floor - Integer(stamp, 10)).abs > tolerance_seconds
+
+      candidates = signature.to_s.split(',').map(&:strip).select { |entry| entry.start_with?('v1=') }
+      return false if candidates.empty?
 
-      expected = signature_header(payload: raw, timestamp: stamp, secret: secret).delete_prefix('v1=')
-      signature.to_s.split(',').map(&:strip).select { |entry| entry.start_with?('v1=') }.any? do |entry|
-        candidate = entry.delete_prefix('v1=').downcase
-        candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(candidate, expected)
+      expected = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{stamp}.".b + raw)
+      # Every candidate is compared, so the time taken does not depend on which one matches.
+      candidates.map { |entry| entry.delete_prefix('v1=').downcase }.reduce(false) do |matched, candidate|
+        (candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(candidate, expected)) || matched
       end
     end
 
-    # Verifies a delivery, then parses it.
-    # @param (see #verify)
+    # Verifies a delivery from its request headers. See {verify}.
+    # @return [Boolean]
+    def verify_request(payload:, headers:, secret:, tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+                       now: Time.now.to_i)
+      verify(payload: payload, headers: headers, secret: secret, tolerance_seconds: tolerance_seconds, now: now)
+    end
+
+    # Verifies a delivery, then parses it. Takes the options of {verify}.
     # @return [WebhookEvent]
     # @raise [WebhookVerificationError] `sdk/invalid-webhook-signature` when verification fails, or
     #   `sdk/invalid-webhook-payload` when the verified body is not an event.
-    def parse_event(payload:, signature:, timestamp:, secret:,
+    def parse_event(payload:, secret:, signature: nil, timestamp: nil, headers: nil,
                     tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, now: Time.now.to_i)
-      unless verify(payload: payload, signature: signature, timestamp: timestamp, secret: secret,
+      unless verify(payload: payload, signature: signature, timestamp: timestamp, headers: headers, secret: secret,
                     tolerance_seconds: tolerance_seconds, now: now)
         raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_SIGNATURE,
                                            'Webhook signature or timestamp did not verify')
@@ -91,32 +147,71 @@ module CalmLens
 
     def decode_event(payload)
       body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
-      unless body.is_a?(Hash) && body['id'].is_a?(String) && body['type'].is_a?(String) && body['createdAt'].is_a?(Integer) &&
-             body['projectId'].is_a?(String) && body['data'].is_a?(Hash)
-        raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not a CalmLens event')
-      end
+      raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not a CalmLens event') unless event?(body)
 
-      WebhookEvent.new(id: body['id'], type: body['type'], created_at: body['createdAt'],
-                       project_id: body['projectId'], data: body['data'])
+      WebhookEvent.new(id: body['id'], project_id: body['projectId'], type: body['type'], severity: body['severity'],
+                       title: body['title'], description: body['description'], asset_id: body['assetId'],
+                       asset: body['asset'], facts: body.fetch('facts', []), created_at: body['createdAt'], payload: body)
     rescue JSON::ParserError, EncodingError => e
       raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not JSON'), cause: e
     end
 
+    # The API's rules for a received body: the fields CalmLens always sends, and the types of the
+    # other known fields when present. Unknown fields are accepted.
+    def event?(body)
+      return false unless body.is_a?(Hash) && body['id'].is_a?(String) && body['type'].is_a?(String) &&
+                          body['projectId'].is_a?(String) && body['createdAt'].is_a?(Numeric)
+
+      optional = ->(key, *types) { !body.key?(key) || types.any? { |type| type.nil? ? body[key].nil? : body[key].is_a?(type) } }
+      asset = body['asset']
+      optional.call('severity', String) && optional.call('title', String) && optional.call('description', String, nil) &&
+        optional.call('assetId', String, nil) && (asset.nil? || (asset.is_a?(Hash) && asset['id'].is_a?(String))) &&
+        (!body.key?('facts') || (body['facts'].is_a?(Array) && body['facts'].all? { |fact| fact?(fact) }))
+    end
+
+    def fact?(fact)
+      fact.is_a?(Hash) && fact['key'].is_a?(String) && fact.key?('value') && (!fact.key?('url') || fact['url'].is_a?(String))
+    end
+
+    # A header's value, found case-insensitively; repeated values are joined with `,`.
+    def header(headers, name)
+      return nil if headers.nil?
+
+      pairs = headers.respond_to?(:to_hash) ? headers.to_hash : headers.to_h
+      rack = "HTTP_#{name.upcase.tr('-', '_')}"
+      found = pairs.select { |key, _| key.to_s.casecmp?(name) || key.to_s == rack }.values
+      return nil if found.empty?
+
+      found.flat_map { |value| Array(value) }.join(',')
+    end
+
     def raw_body(payload)
       return payload.b if payload.is_a?(String)
 
       raise Internal.invalid("Webhook payload must be the raw body String, not a #{payload.class}. " \
                              'Read request.raw_post (Rails) or request.body.read (Rack, Sinatra) before parsing.')
     end
-    private_class_method :decode_event, :raw_body
+    private_class_method :decode_event, :event?, :fact?, :header, :raw_body
   end
 
   # @see Webhooks.signature_header
   def self.create_webhook_signature_header(...) = Webhooks.signature_header(...)
 
+  # @see Webhooks.headers
+  def self.create_webhook_headers(...) = Webhooks.headers(...)
+
+  # @see Webhooks.to_payload
+  def self.to_webhook_event_payload(...) = Webhooks.to_payload(...)
+
   # @see Webhooks.verify
   def self.verify_webhook_signature(...) = Webhooks.verify(...)
 
+  # @see Webhooks.verify_request
+  def self.verify_webhook_request(...) = Webhooks.verify_request(...)
+
   # @see Webhooks.parse_event
   def self.parse_webhook_event(...) = Webhooks.parse_event(...)
+
+  # @see Webhooks.test_event?
+  def self.test_webhook_event?(...) = Webhooks.test_event?(...)
 end

data/lib/calmlens.rb

@@ -15,8 +15,10 @@ require_relative 'calmlens/transport'
 require_relative 'calmlens/upload_body'
 require_relative 'calmlens/session'
 require_relative 'calmlens/resource'
+require_relative 'calmlens/moderation_context'
 require_relative 'calmlens/assets'
 require_relative 'calmlens/folders'
+require_relative 'calmlens/hash_lists'
 require_relative 'calmlens/text'
 require_relative 'calmlens/upload_tokens'
 require_relative 'calmlens/events'