calmlens 0.18.2 → 0.19.0

data/lib/calmlens/testing/test_image_grid.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module CalmLens
+  # The image grid behind the signed test images (test_inputs.rb).
+  module TestInputs
+    # The test image grid of packages/shared/src/TestImageGrid.ts, painted byte for byte: an odd
+    # N×N grid with an alternating black-and-white ring, two Gray-coded bits per interior cell as
+    # one of four luma levels (colour in chroma only), and Reed–Solomon parity over GF(256).
+    # @api private
+    module Grid
+      # Target luma of the four data levels.
+      LEVELS = [72, 128, 184, 240].freeze
+      SYMBOL_LEVEL = [0, 1, 3, 2].freeze
+      PARITY = 32
+      # Category colours, carried in the chroma only.
+      COLORS = {
+        'sexual' => [232, 80, 160], 'violence' => [224, 56, 64], 'self-harm' => [24, 168, 152],
+        'harassment' => [240, 128, 48], 'hate' => [144, 80, 216], 'criminal-activity' => [224, 184, 40],
+        'personal-information' => [48, 128, 224], 'profanity' => [136, 192, 48]
+      }.freeze
+      NEUTRAL = [144, 152, 160].freeze
+
+      # GF(256) with the polynomial 0x11d and generator 2.
+      EXP = Array.new(512, 0)
+      LOG = Array.new(256, 0)
+      x = 1
+      255.times do |i|
+        EXP[i] = x
+        LOG[x] = i
+        x <<= 1
+        x ^= 0x11d if x.anybits?(256)
+      end
+      (255...512).each { |i| EXP[i] = EXP[i - 255] }
+      [EXP, LOG].each(&:freeze)
+
+      module_function
+
+      def mul(left, right) = left.zero? || right.zero? ? 0 : EXP[LOG[left] + LOG[right]]
+
+      # g(x) = (x - a^0)...(x - a^31), highest coefficient first.
+      GENERATOR = PARITY.times.reduce([1]) do |g, i|
+        following = Array.new(g.size + 1, 0)
+        g.each_with_index do |coefficient, j|
+          following[j] ^= coefficient
+          following[j + 1] ^= mul(coefficient, EXP[i])
+        end
+        following
+      end.freeze
+
+      def parity(block)
+        parity = Array.new(PARITY, 0)
+        block.each do |byte|
+          factor = byte ^ parity[0]
+          parity = parity.drop(1) << 0
+          PARITY.times { |j| parity[j] ^= mul(GENERATOR[j + 1], factor) } unless factor.zero?
+        end
+        parity
+      end
+
+      # The codeword bytes a grid of `cells` holds, its block lengths and its data bytes.
+      def layout(cells)
+        capacity = (cells - 2) * (cells - 2) / 4
+        blocks = (capacity + 254) / 255
+        lengths = Array.new(blocks) { |index| (capacity / blocks) + (index < capacity % blocks ? 1 : 0) }
+        [capacity, lengths, capacity - (blocks * PARITY)]
+      end
+
+      # The colour's chroma on the level's luma, scaled by the largest s/16 that keeps every
+      # channel in 0-255. Each scaled difference is truncated toward zero (not floored).
+      def pixel(colour, level)
+        target = LEVELS[level]
+        own = ((77 * colour[0]) + (150 * colour[1]) + (29 * colour[2])) >> 8
+        16.downto(0) do |scale|
+          pixel = colour.map do |channel|
+            difference = channel - own
+            magnitude = (difference.abs * scale) >> 4
+            difference.negative? ? target - magnitude : target + magnitude
+          end
+          return pixel if pixel.all? { |channel| channel.between?(0, 255) }
+        end
+      end
+
+      # The data cell's colour: the palette blended between opposite corners, in integers.
+      def blend(palette, column, row, cells)
+        span = cells - 1
+        denominator = span * span
+        position = ((column * (span - row)) + ((span - column) * row)) * (palette.size - 1)
+        start = position / denominator
+        remainder = position - (start * denominator)
+        finish = palette[[start + 1, palette.size - 1].min]
+        palette[start].each_with_index.map do |channel, c|
+          ((channel * (denominator - remainder)) + (finish[c] * remainder)) / denominator
+        end
+      end
+
+      # Paints `data` (a binary String) as a grid of the categories' colours: [width, RGBA String].
+      def paint(data, categories)
+        cells = (15..127).step(2).find { |size| layout(size)[2] >= data.bytesize }
+        raise Internal.invalid('Test scenario is too large for a test image') unless cells
+
+        stream = codeword_stream(data, cells)
+        palette = categories.uniq.map { |category| COLORS.fetch(category) }
+        palette = [NEUTRAL] if palette.empty?
+        pixels = Array.new(cells * cells) { |cell| [*cell_pixel(stream, palette, cell, cells), 255].pack('C4') }
+        cell_size = 2 * (512 / 2 / cells)
+        rows = Array.new(cells) { |row| pixels[row * cells, cells].map { |pixel| pixel * cell_size }.join * cell_size }
+        [cells * cell_size, rows.join.b]
+      end
+
+      # The padded data with each block's parity, the blocks interleaved byte by byte and whitened, so
+      # a uniform area never reads as the all-zero codeword.
+      def codeword_stream(data, cells)
+        _, lengths, data_bytes = layout(cells)
+        padded = data.bytes + Array.new(data_bytes - data.bytesize) { |i| i.odd? ? 0x11 : 0xec }
+        offset = 0
+        codewords = lengths.map do |length|
+          block = padded[offset, length - PARITY]
+          offset += block.size
+          block + parity(block)
+        end
+        stream = Array.new(lengths.max) { |i| codewords.filter_map { |codeword| codeword[i] } }.flatten
+        stream.each_with_index.map { |byte, i| byte ^ (((i * 151) + 77) & 255) }
+      end
+
+      # A cell's RGB: the ring alternates black and white; data cells hold two bits each.
+      def cell_pixel(stream, palette, cell, cells)
+        row, column = cell.divmod(cells)
+        return [(row + column).odd? ? 255 : 0] * 3 if [row, column].any? { |at| at.zero? || at == cells - 1 }
+
+        symbol = ((row - 1) * (cells - 2)) + column - 1
+        index = symbol >> 2
+        level = index < stream.size ? SYMBOL_LEVEL[(stream[index] >> (6 - (2 * (symbol & 3)))) & 3] : 0
+        pixel(blend(palette, column, row, cells), level)
+      end
+    end
+
+    # The PNG encoding of test images.
+    # @api private
+    module Png
+      module_function
+
+      # 8-bit RGBA rows without filtering in stored deflate blocks, so every SDK writes the same bytes.
+      def png(width, height, rgba)
+        stride = width * 4
+        raw = Array.new(height) { |row| "\0".b + rgba.byteslice(row * stride, stride) }.join
+        zlib = "\x78\x01".b
+        blocks = (0...raw.bytesize).step(65_535).map { |offset| raw.byteslice(offset, 65_535) }
+        blocks.each_with_index do |block, index|
+          zlib << [index == blocks.size - 1 ? 1 : 0, block.bytesize, block.bytesize ^ 0xffff].pack('Cvv') << block
+        end
+        zlib << [Zlib.adler32(raw)].pack('N')
+        chunk = ->(type, body) { [body.bytesize].pack('N') + type.b + body + [Zlib.crc32(type.b + body)].pack('N') }
+        "\x89PNG\r\n\x1a\n".b + chunk.call('IHDR', [width, height, 8, 6, 0, 0, 0].pack('NNC5')) +
+          chunk.call('IDAT', zlib) + chunk.call('IEND', ''.b)
+      end
+    end
+    private_constant :Grid, :Png
+  end
+end

data/lib/calmlens/testing/test_input_scenario.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'classification'
+
+module CalmLens
+  # The scenario checks behind the signed test inputs (test_inputs.rb).
+  module TestInputs
+    # Checks test input scenarios and writes them as the backend's canonical JSON.
+    # @api private
+    module Scenario
+      ACTIONS = %w[allow limit age-restrict block].freeze
+      REGIONAL_ACTIONS = %w[limit age-restrict block].freeze
+      # The qualifiers a scenario may list for each category: all but those the input type sets.
+      ALLOWED_QUALIFIERS = MockClassification::QUALIFIERS.transform_values do |list|
+        (list - MockClassification::INPUT_QUALIFIERS).freeze
+      end.freeze
+
+      module_function
+
+      # A checked scenario's JSON in the backend's key order. Every string is a validated ASCII token.
+      def canonical_json(value)
+        case value
+        when Hash then "{#{value.map { |key, item| "\"#{key}\":#{canonical_json(item)}" }.join(',')}}"
+        when Array then "[#{value.map { |item| canonical_json(item) }.join(',')}]"
+        when Float then js_number(value)
+        else "\"#{value}\""
+        end
+      end
+
+      # A score as JavaScript's JSON.stringify writes it: the shortest round-tripping digits, in
+      # exponent form below 1e-6, and 0 for -0.
+      def js_number(value)
+        return '0' if value.zero?
+
+        mantissa, exponent = value.to_s.split('e')
+        whole, fraction = mantissa.split('.')
+        digits = whole + fraction.to_s
+        point = whole.size + exponent.to_i
+        stripped = digits.sub(/\A0+/, '')
+        point -= digits.size - stripped.size
+        digits = stripped.sub(/0+\z/, '')
+        if value < 1e-6
+          "#{digits[0]}#{".#{digits[1..]}" if digits.size > 1}e#{point - 1}"
+        elsif point <= 0 then "0.#{'0' * -point}#{digits}"
+        elsif point >= digits.size then digits + ('0' * (point - digits.size))
+        else "#{digits[0, point]}.#{digits[point..]}"
+        end
+      end
+
+      # Checks a scenario and returns it with camelCase String keys in canonical order.
+      def validate(input)
+        input = fields(input, 'scenario', %w[regionalActions unassessedCategories instances], %w[instances])
+        instances = array(input['instances'], 'instances', 128).map { |instance| check_instance(instance) }
+        with_action = instances.count { |instance| instance.key?('action') }
+        check([0, instances.size].include?(with_action), 'Set an action for every instance or omit all actions')
+        checked = {}
+        if input.key?('regionalActions')
+          checked['regionalActions'] = array(input['regionalActions'], 'regionalActions', REGIONS.size).each_with_object([]) do |item, done|
+            item = fields(item, 'regional action', %w[region action], %w[region action])
+            check(REGIONS.include?(item['region']) && done.none? { |other| other['region'] == item['region'] },
+                  "Regional actions need unique regions from #{REGIONS.join(', ')} (got #{item['region'].inspect})")
+            check(REGIONAL_ACTIONS.include?(item['action']), "Regional action must be one of #{REGIONAL_ACTIONS.join(', ')}")
+            done << { 'region' => item['region'], 'action' => item['action'] }
+          end
+        end
+        if input.key?('unassessedCategories')
+          unassessed = array(input['unassessedCategories'], 'unassessedCategories', MockClassification::CATEGORIES.size)
+          unassessed.each_with_index do |category, index|
+            check(MockClassification::CATEGORIES.include?(category) && !unassessed[0, index].include?(category) &&
+                    instances.none? { |instance| instance['category'] == category },
+                  "Unassessed categories must be unique categories without instances (got #{category.inspect})")
+          end
+          checked['unassessedCategories'] = unassessed
+        end
+        checked.merge('instances' => instances)
+      end
+
+      def check_instance(instance)
+        instance = fields(instance, 'instance', %w[category score action qualifiers], %w[category qualifiers])
+        category = instance['category']
+        allowed = ALLOWED_QUALIFIERS[category] if category.is_a?(String)
+        check(allowed, "Unknown category #{category.inspect}")
+        checked = { 'category' => category }
+        if instance.key?('score')
+          score = instance['score']
+          check(score.is_a?(Numeric) && score.real? && score.to_f.between?(0, 1), 'Score must be a number from 0 to 1')
+          checked['score'] = score.to_f
+        end
+        if instance.key?('action')
+          check(ACTIONS.include?(instance['action']), "Action must be one of #{ACTIONS.join(', ')}")
+          checked['action'] = instance['action']
+        end
+        qualifiers = array(instance['qualifiers'], 'qualifiers', 64)
+        qualifiers.each_with_index do |qualifier, index|
+          check(allowed.include?(qualifier) && !qualifiers[0, index].include?(qualifier),
+                "Choose unique #{category} qualifiers; input-type qualifiers are automatic (got #{qualifier.inspect})")
+        end
+        checked.merge('qualifiers' => qualifiers)
+      end
+
+      # A Hash's entries by camelCase key, refusing unknown, duplicate and missing keys.
+      def fields(value, name, allowed, required)
+        check(value.is_a?(Hash), "A test #{name} must be a Hash (got #{value.class})")
+        result = {}
+        value.each do |key, item|
+          field = Internal.camelize(key) if key.is_a?(String) || key.is_a?(Symbol)
+          check(allowed.include?(field), "Unknown test #{name} field #{key.inspect}")
+          check(!result.key?(field), "Test #{name} field #{field} is given twice")
+          result[field] = item
+        end
+        missing = required - result.keys
+        check(missing.empty?, "A test #{name} needs #{missing.join(', ')}")
+        result
+      end
+
+      def array(value, name, max)
+        check(value.is_a?(Array), "#{name} must be an Array")
+        check(value.size <= max, "#{name} has at most #{max} items")
+        value.dup
+      end
+
+      def check(condition, message) = condition || raise(Internal.invalid(message))
+    end
+
+    private_constant :Scenario
+  end
+end

data/lib/calmlens/testing/test_inputs.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require_relative 'classification'
+require_relative 'test_input_scenario'
+require_relative 'test_image_grid'
+
+module CalmLens
+  # Signed test inputs: text codes, test images and media phrases that a project's moderation
+  # recognises as a declared scenario when they are signed with its secret test input key (shown in
+  # the portal's project settings), so CalmLens returns that scenario instead of classifying them.
+  # The formats match the JavaScript SDK's `calmlens/test-inputs` byte for byte.
+  #
+  # A scenario is a Hash with the API's keys, as Strings or Symbols (snake_case keys are converted
+  # to camelCase like other options):
+  # `{ 'regionalActions' => [{ 'region' => 'DE', 'action' => 'block' }], 'unassessedCategories' => ['profanity'],
+  # 'instances' => [{ 'category' => 'harassment', 'score' => 0.9, 'action' => 'block', 'qualifiers' => ['harassment-abuse'] }] }`.
+  # `instances` (at most 128) and each instance's `qualifiers` (unique qualifiers of its category, at
+  # most 64; input-type qualifiers such as `sexual-text` are automatic) are required; `score` (0 to
+  # 1) and `action` (`allow`, `limit`, `age-restrict` or `block`, on every instance or none) are
+  # optional. `unassessedCategories` lists categories reported as not assessed, none with instances;
+  # `regionalActions` gives up to one `limit`, `age-restrict` or `block` action for each of
+  # {REGIONS}. Values are Strings and Numerics. An absent list is left out of the signed scenario;
+  # an empty one is sent as `[]`. Anything else raises `sdk/invalid-argument`.
+  #
+  # @example
+  #   code = CalmLens::TestInputs.generate_text_code('harassment.insult', test_input_key)
+  #   png = CalmLens::TestInputs.paint_image('violence', test_input_key).png
+  #   phrase = CalmLens::TestInputs.generate_media_code('violence', test_input_key)
+  module TestInputs
+    # A painted test image: `width` by `height` pixels of 8-bit RGBA, row by row, in the binary
+    # String `rgba`, and the same image as binary PNG bytes in `png`.
+    Image = Struct.new(:width, :height, :rgba, :png, keyword_init: true)
+
+    # The regions a regional action can name.
+    REGIONS = %w[DE AT FR GB EU AU BR].freeze
+    # The signals {generate_text_code}, {paint_image} and {for_signal} accept: the categories and
+    # five named shortcuts.
+    SIGNALS = (MockClassification::CATEGORIES +
+               %w[sexual.involving-minors harassment.insult sexual.adult hate.regional-symbol violence.graphic]).freeze
+    # The signals {generate_media_code} accepts.
+    MEDIA_SIGNALS = (MockClassification::CATEGORIES + %w[violence.graphic]).freeze
+
+    one = ->(category, *qualifiers) { { 'instances' => [{ 'category' => category, 'qualifiers' => qualifiers }] } }
+    deep_freeze = lambda do |value|
+      value.each_value { |item| deep_freeze.call(item) } if value.is_a?(Hash)
+      value.each { |item| deep_freeze.call(item) } if value.is_a?(Array)
+      value.freeze
+    end
+    # Ready-made scenarios (deeply frozen): a clean input, a limited one, adult images and text,
+    # regional delivery, content restricted in Germany, and mixed instances in one category.
+    PRESETS = deep_freeze.call(
+      clean: { 'instances' => [] },
+      limited: one.call('harassment', 'harassment-abuse'),
+      adult_image: one.call('sexual', 'sexual-pornographic-media'),
+      adult_text: one.call('sexual', 'sexual-explicit-language'),
+      regional_delivery: { 'instances' => [], 'regionalActions' => [{ 'region' => 'DE', 'action' => 'block' },
+                                                                    { 'region' => 'GB', 'action' => 'age-restrict' },
+                                                                    { 'region' => 'FR', 'action' => 'limit' }] },
+      germany: one.call('hate', 'hate-symbol', 'hate-nazi-symbols-public-display'),
+      mixed: { 'instances' => [{ 'category' => 'harassment', 'qualifiers' => %w[harassment-abuse harassment-documentary] },
+                               { 'category' => 'harassment', 'qualifiers' => ['harassment-threat'] }] }
+    )
+
+    HEX_WORDS = %w[zero one two three four five six seven eight nine alpha bravo charlie delta echo foxtrot].freeze
+    private_constant :HEX_WORDS
+
+    module_function
+
+    # The scenario a signal (one of {SIGNALS}) stands for in a text input (`kind` `'text'`) or an
+    # image (`'image'`), as a new Hash. {generate_text_code} uses the text kind and {paint_image}
+    # the image kind.
+    # @param signal [String]
+    # @param kind [String] `'text'` or `'image'`
+    # @return [Hash{String => Object}]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an unknown signal or kind
+    def for_signal(signal, kind = 'text')
+      raise Internal.invalid("Test input kind must be text or image (got #{kind.inspect})") unless %w[text image].include?(kind)
+
+      preset = case signal
+               when 'harassment.insult' then PRESETS[:limited]
+               when 'sexual.adult' then PRESETS[kind == 'image' ? :adult_image : :adult_text]
+               when 'hate.regional-symbol' then PRESETS[:germany]
+               when 'sexual.involving-minors' then { 'instances' => [{ 'category' => 'sexual', 'qualifiers' => ['sexual-minors'] }] }
+               when 'violence.graphic' then { 'instances' => [{ 'category' => 'violence', 'qualifiers' => ['violence-graphic'] }] }
+               when *MockClassification::CATEGORIES then { 'instances' => [{ 'category' => signal, 'qualifiers' => [] }] }
+               else raise Internal.invalid("Unknown test signal #{signal.inspect}")
+               end
+      Marshal.load(Marshal.dump(preset))
+    end
+
+    # The signed text code for a scenario or a signal (one of {SIGNALS}): put it anywhere in a text
+    # input.
+    # @param input [Hash, String] a scenario or a signal
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [String]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key, scenario or signal
+    def generate_text_code(input, test_input_key)
+      text_code(scenario(input, 'text', test_input_key), test_input_key)
+    end
+
+    # Paints the signed test image for a scenario or a signal (one of {SIGNALS}): a grid that
+    # survives lossy formats and resizing. Upload its `png`, or encode its `rgba` in any format.
+    # @param input [Hash, String] a scenario or a signal
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [Image]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key, scenario or signal, or
+    #   a scenario too large for a test image
+    def paint_image(input, test_input_key)
+      checked = scenario(input, 'image', test_input_key)
+      signature = text_code(checked, test_input_key).split[1]
+      content = Scenario.canonical_json(checked).b
+      data = [content.bytesize].pack('n') + [signature].pack('H*') + content
+      width, rgba = Grid.paint(data, checked['instances'].map { |instance| instance['category'] })
+      Image.new(width: width, height: width, rgba: rgba, png: Png.png(width, width, rgba))
+    end
+
+    # The phrase that triggers a signal (one of {MEDIA_SIGNALS}) in audio or video: read it aloud,
+    # or show it as large, high-contrast text in a frame.
+    # @param signal [String]
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [String]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key or signal
+    def generate_media_code(signal, test_input_key)
+      raise Internal.invalid("Unsupported media test signal #{signal.inspect}") unless MEDIA_SIGNALS.include?(signal)
+
+      check_key(test_input_key)
+      words = tag(test_input_key, "calmlens-test:media:#{signal}").each_char.map { |digit| HEX_WORDS[digit.to_i(16)] }
+      ['Calm Lens test', *words, signal.tr('.-', '  '), 'end test'].join(' ')
+    end
+
+    # The checked scenario for an input or signal, in canonical form.
+    def scenario(input, kind, test_input_key)
+      check_key(test_input_key)
+      Scenario.validate(input.is_a?(String) ? for_signal(input, kind) : input)
+    end
+
+    def text_code(checked, test_input_key)
+      payload = [Scenario.canonical_json(checked)].pack('m0').tr('+/', '-_').delete('=')
+      raise Internal.invalid('Test scenario is too large') if payload.bytesize > 8000
+
+      "<!calmlens-test #{tag(test_input_key, "calmlens-test:v1:#{payload}")} #{payload}>"
+    end
+
+    def check_key(key)
+      return if key.is_a?(String) && key.match?(/\A[a-f0-9]{32}\z/)
+
+      raise Internal.invalid('The test input key must be 32 lowercase hexadecimal characters')
+    end
+
+    # The first 32 hex characters of HMAC-SHA256 with the key's ASCII bytes.
+    def tag(key, message) = OpenSSL::HMAC.hexdigest('SHA256', key, message)[0, 32]
+
+    private_class_method :scenario, :text_code, :check_key, :tag
+  end
+end

data/lib/calmlens/testing.rb

@@ -5,6 +5,7 @@ require 'securerandom'
 require 'uri'
 require_relative '../calmlens'
 require_relative 'testing/fake_api'
+require_relative 'testing/test_inputs'
 
 module CalmLens
   # An offline client for tests. Calls run the real client's validation, encoding, retries and
@@ -63,6 +64,7 @@ module CalmLens
                               retry explain wait_for_decision delete_content delete batch],
                    folders: %i[list retrieve create update delete move],
                    hash_lists: %i[list retrieve create update delete list_entries add_entry remove_entry],
+                   policies: %i[list retrieve create update apply_preset set_automatic_updates delete assign],
                    text: %i[classify], events: %i[list],
                    cdn: %i[serve] }.freeze
     private_constant :OPERATIONS
@@ -144,7 +146,8 @@ module CalmLens
     #   runs while the mock handles a request, so it must not call the mock.
     # @param max_retries [Integer] retries after a retryable failure; 0 by default, so a simulated
     #   failure reaches the caller.
-    # @param options [Hash] other {ServerClient#initialize} settings, except `api_key` and `transport`.
+    # @param options [Hash] other {ServerClient#initialize} settings, such as `part_size_bytes`, except
+    #   `api_key` and `transport`.
     #   Retries and decision checks wait no real time.
     def initialize(project_id: 'project-1', api_key: MockServerClient.create_api_key, base_url: 'https://api.calmlens.invalid/v1',
                    cdn_base_url: 'https://cdn.calmlens.invalid/v1', now: MockServerClient.monotonic_clock,
@@ -338,6 +341,8 @@ module CalmLens
       path, query = Internal.split_url(request.url).last.split('?', 2)
       base = request.url.start_with?("#{cdn_base_url}/") ? URI(cdn_base_url).path : URI(base_url).path
       call = Thread.current[@call_key]
+      # The later parts of a content upload sent in parts count as assets.uploadPart.
+      call = { operation: 'assets.uploadPart' } if request.method == 'POST' && path.delete_prefix(base).match?(%r{\A/assets/[^/]+/part\z})
       @mock_lock.synchronize do
         record = Request.new(method: request.method, url: request.url, path: decode_path(path.delete_prefix(base)),
                              query: URI.decode_www_form(query.to_s).to_h, headers: request.headers.dup, body: body)

data/lib/calmlens/text.rb

@@ -3,6 +3,9 @@
 module CalmLens
   # Text moderation shortcuts. Reach it through {ServerClient#text}.
   class Text < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'text'
+
     # @api private
     def initialize(session, assets)
       super(session)
@@ -17,11 +20,9 @@ module CalmLens
     # @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 }
+      api, request = call(options, __method__) { |*split| split }
       text = api['text']
-      unless text.is_a?(String) && !text.strip.empty?
-        raise Internal.invalid('Text to classify must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
-      end
+      raise Internal.invalid('Text to classify must be a non-empty string') unless text.is_a?(String) && !text.strip.empty?
 
       @assets.classify(without(api, 'text').merge('name' => api.fetch('name', 'text'),
                                                   'content' => { 'plainText' => text, 'type' => 'text/plain' },

data/lib/calmlens/transforms.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module CalmLens
-  # CDN transform selectors: selector Strings and structured steps serialized the way every SDK does.
+  # CDN transform selectors: selector Strings and structured options serialized the way every SDK does.
   # @api private
   module Transforms
     module_function
@@ -14,46 +14,39 @@ module CalmLens
     # </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}.
+    # Returns the selector the API and CDN accept for a transform: a selector String checked and
+    # unchanged, or structured options (`{width: 640, fit: 'cover'}`) serialized by {serialize}.
     def selector(value)
-      value.nil? || value.is_a?(String) ? value : serialize(value)
+      return serialize(value) unless value.nil? || value.is_a?(String)
+      # A transform is one path segment of options: it must not add a segment, lens, query or fragment.
+      if value&.match?(%r{[/?#]}) || value&.include?('..') || value&.start_with?('@')
+        raise Internal.invalid('Transform cannot contain "/", "..", "?" or "#", or start with "@"')
+      end
+
+      value
     end
 
-    # 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.
+    # Builds the CDN path text of a transform. A selector String is encoded like JavaScript's
+    # encodeURI; serialized options 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?(/[?#]/)
+      text = selector(value)
+      return text unless value.is_a?(String)
 
       # 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, 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.
+    # Serializes structured transform options as a CDN selector, such as `fit=cover,width=640`. 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?
-
-      steps.map do |step|
-        raise Internal.invalid('Transform steps must be Hashes') unless step.is_a?(Hash)
-
-        step = step.transform_keys(&:to_s)
-        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)
+      raise Internal.invalid('Transform options must be a Hash') unless value.is_a?(Hash)
 
-        pairs = []
-        sorted_options(options).each { |key, item| append_pairs(pairs, key, item) }
-        raise Internal.invalid('Transform steps need at least one option') if pairs.empty?
+      pairs = []
+      sorted_options(value).each { |key, item| append_pairs(pairs, key, item) }
+      raise Internal.invalid('A transform needs at least one option') if pairs.empty?
 
-        pairs.join(',')
-      end.join('/')
+      pairs.join(',')
     end
 
     def sorted_options(options, prefix = '')

data/lib/calmlens/upload_body.rb

@@ -90,6 +90,14 @@ module CalmLens
       @source.rewind unless @source.is_a?(String)
     end
 
+    # `length` bytes from `offset` as a body of their own, read again from the source for each
+    # attempt. Only for a {#replayable?} body of known size: an IO is positioned at the slice.
+    def slice(offset, length)
+      return UploadBody.new(@source.byteslice(offset, length)) if @source.is_a?(String)
+
+      UploadBody.new(@source.slice(offset, length))
+    end
+
     # The bytes, read fully. Used only by the offline mock.
     def read_all
       return @source if @source.is_a?(String)
@@ -114,6 +122,12 @@ module CalmLens
 
       def rewindable? = !@start.nil?
 
+      # A reader of `length` bytes from `offset` of this rewindable stream, positioned there.
+      def slice(offset, length)
+        @io.seek(@start + offset)
+        IOReader.new(@io, length)
+      end
+
       def rewind
         @io.seek(@start)
         @remaining = @size

data/lib/calmlens/upload_tokens.rb

@@ -9,6 +9,9 @@ module CalmLens
   # Signs upload tokens, which let a browser upload through an upload preset. Reach it through
   # {ServerClient#upload_tokens}. Signing happens locally with the API key; no request is made.
   class UploadTokens < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'uploadTokens'
+
     TOKEN_PREFIX = 'clut_'
     SIGNING_CONTEXT = 'calmlens-upload-token:v1:'
     DEFAULT_TTL_SECONDS = 600
@@ -26,7 +29,7 @@ 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)
-      call(options) { UploadTokens.sign_at(@api_key, options, now: (Time.now.to_f * 1000).to_i, nonce: SecureRandom.uuid) }
+      call(options, __method__) { 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}

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.18.2'
+  VERSION = '0.19.0'
 end

data/lib/calmlens.rb

@@ -8,6 +8,7 @@ end
 require_relative 'calmlens/version'
 require_relative 'calmlens/error_codes'
 require_relative 'calmlens/errors'
+require_relative 'calmlens/option_keys'
 require_relative 'calmlens/internal'
 require_relative 'calmlens/transforms'
 require_relative 'calmlens/response'
@@ -19,6 +20,7 @@ require_relative 'calmlens/moderation_context'
 require_relative 'calmlens/assets'
 require_relative 'calmlens/folders'
 require_relative 'calmlens/hash_lists'
+require_relative 'calmlens/policies'
 require_relative 'calmlens/text'
 require_relative 'calmlens/upload_tokens'
 require_relative 'calmlens/events'