calmlens 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2bd7df72a5d1e781b05bf67d5ef915c50719072e906feb6b224f69aba1073c4
-  data.tar.gz: b81cd9b22c1e11a926cb2e39e2cace6a47dc0507ff0e96fd7e1fbaf3cba6f5cf
+  metadata.gz: b3b2b65d6e8ec874bb4971fd4e4568e6cc424ecce6f060c6ce796bc2eb1a1c6d
+  data.tar.gz: 54a14554c90bec933b2ebaf0482918f3902497c6bdff6d8204e6b374fb881aab
 SHA512:
-  metadata.gz: aa214b8c98aff276dccce6b3a2e2d9c6f1a24a0f47387512af8262d9eba91c40973d93113df9903ffc950e8cbc906648c2fd9c3b493405d612edca465147667a
-  data.tar.gz: 1e512158a2d93e611e8611cbbb838d260112cb9e4c672ff1e3d60b76e62ac5f247016ffe162ddfd766caa39e3b063a970c2c9b97a310941cf920cedd78741282
+  metadata.gz: 899100986bd5d7534a535a92f1af8c91a06fe8eadd123dfb9ef03a63d22193536c6d3bdaf72936905bee03379e88a3bb53e8197ae259fddec8b32e1d0eb951b8
+  data.tar.gz: 33d8fa683ba8d59117f9be22611f0ba5a12b4b2d557a4bbf61cdfd3b782f1d4186a3197bdaf3e26df8e0ff07c8ed53ca79e0bdeb84feae3d1f9ce904976ae7c6

data/lib/calmlens/assets.rb

@@ -510,10 +510,11 @@ module CalmLens
 
     def check_mime(type)
       mime = type.to_s.split(';').first.to_s.strip.downcase
-      if mime.empty? || mime == 'application/octet-stream' || mime.start_with?('multipart/')
-        raise Internal.invalid("#{mime} is not a valid upload file type. Uploads must use a concrete file MIME type " \
-                               'that CalmLens can store and process, such as image/png, image/jpeg, ' \
-                               'application/pdf, or text/plain.', ErrorCodes::INVALID_UPLOAD_MIME_TYPE)
+      unless Internal.accepted_upload_mime_type?(mime)
+        raise InvalidArgumentError.new(ErrorCodes::INVALID_UPLOAD_MIME_TYPE,
+                                       "#{mime} is not a valid upload file type. Uploads must use a concrete file MIME " \
+                                       'type that CalmLens can store and process, such as image/png, image/jpeg, ' \
+                                       'application/pdf, or text/plain.', details: { 'mimeType' => type })
       end
       raise Internal.invalid('Content type cannot contain line breaks') unless type.match?(Internal::HEADER_VALUE)
 

data/lib/calmlens/internal.rb

@@ -79,6 +79,16 @@ module CalmLens
       value.is_a?(Numeric) && value.real? && value.to_f.finite? && value.positive?
     end
 
+    # Whether the API accepts an upload of this MIME type: an image, audio, video, text, document or
+    # website type, not a container such as `application/octet-stream`. It refuses any other type
+    # with `upload/invalid-mime-type`.
+    def accepted_upload_mime_type?(type)
+      mime = type.to_s.split(';', 2).first.to_s.strip.downcase
+      return false if UPLOAD_MIME_REJECTED.include?(mime)
+
+      mime.start_with?(*UPLOAD_MIME_PREFIXES) || mime.end_with?(*UPLOAD_MIME_SUFFIXES) || UPLOAD_MIME_TYPES.include?(mime)
+    end
+
     # Fetches a required option.
     def required(options, key, code = SdkErrorCodes::INVALID_ARGUMENT)
       raise invalid("#{key} is required", code) unless options.key?(key)

data/lib/calmlens/lenses.rb

@@ -7,12 +7,13 @@ module CalmLens
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
     OPERATIONS = nil
 
+    # Lens definitions are sent as given, nil fields included.
     def ensure_lenses(options)
-      call(options, __method__) { |api, request| @session.ensure_lenses(api['lenses'], request) }
+      call(options, __method__, keep_nil: true) { |api, request| @session.ensure_lenses(api['lenses'], request) }
     end
 
     def ensure_lens(options)
-      call(options, __method__) { |api, request| @session.ensure_lenses([api], request).first }
+      call(options, __method__, keep_nil: true) { |api, request| @session.ensure_lenses([api], request).first }
     end
   end
   private_constant :Lenses

data/lib/calmlens/option_keys.rb

@@ -62,5 +62,28 @@ module CalmLens
         uploadPresetId visibility
       ].freeze
     }.freeze
+
+    # The option keys each method sends as null when given nil; any other option given as nil
+    # is left out, as the API refuses null for it.
+    NULLABLE_OPTION_KEYS = {
+      'assets.classify' => %w[
+        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+      ].freeze,
+      'assets.create' => %w[
+        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+      ].freeze,
+      'assets.each' => %w[filter folderId].freeze,
+      'assets.list' => %w[filter folderId].freeze,
+      'assets.move' => %w[folderId].freeze,
+      'assets.update' => %w[description externalId externalUrl metadata tags visibility].freeze,
+      'folders.create' => %w[parentId].freeze,
+      'folders.move' => %w[parentId].freeze,
+      'hashLists.addEntry' => %w[label quality].freeze,
+      'hashLists.create' => %w[description].freeze,
+      'hashLists.update' => %w[description].freeze,
+      'text.classify' => %w[
+        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+      ].freeze
+    }.freeze
   end
 end

data/lib/calmlens/policies.rb

@@ -61,9 +61,9 @@ module CalmLens
       end
     end
 
-    # Switches automatic updates on or off for the project's preset policy. Switching on replaces
-    # the saved copy with the latest preset settings under the same ID; switching off pins the
-    # current preset version as a copy with unchanged settings.
+    # Switches automatic updates on or off for the organisation's own preset policy. Switching on
+    # replaces the saved copy with the latest preset settings under the same ID; switching off pins
+    # the current preset version as a copy with unchanged settings.
     # @option options [String] :policy_id
     # @option options [Boolean] :enabled
     # @option options [Integer] :revision the policy's current revision

data/lib/calmlens/resource.rb

@@ -28,9 +28,15 @@ module CalmLens
     # Runs a public method: splits options, and raises every argument problem as {InvalidArgumentError}.
     # `method` names the public method: an option it doesn't take, such as a misspelt one, raises
     # `sdk/invalid-argument` instead of being silently dropped.
-    def call(options, method)
-      check_option_keys(options, [self.class::OPERATIONS, Internal.camelize(method)].compact.join('.'))
+    # An option given as nil is left out, as if omitted, unless the API takes null for it
+    # (Internal::NULLABLE_OPTION_KEYS), such as `description: nil` to clear a description;
+    # `keep_nil: true` sends every option as given, as for a lens definition.
+    def call(options, method, keep_nil: false)
+      operation = [self.class::OPERATIONS, Internal.camelize(method)].compact.join('.')
+      check_option_keys(options, operation)
       api, request = Internal.options(options)
+      nullable = Internal::NULLABLE_OPTION_KEYS.fetch(operation, [])
+      api = api.reject { |key, value| value.nil? && !nullable.include?(key) } unless keep_nil
       yield api, request
     rescue Error
       raise

data/lib/calmlens/testing/fake_api.rb

@@ -240,6 +240,47 @@ module CalmLens
       # A request the API's schema refuses: `validation/<issue>` with HTTP 400 and the field.
       def invalid!(code, path) = raise(Failure.new(code, "Invalid #{path}", details: { 'path' => path }, status: 400))
 
+      # Like the API's schema (METADATA_ITEM_SCHEMA): metadata is nil or a list of `{id, value}`
+      # Hashes with a String `id` and any JSON `value`.
+      def check_metadata(metadata)
+        return if metadata.nil?
+
+        invalid!('validation/invalid-type', 'metadata') unless metadata.is_a?(Array)
+        metadata.each_with_index do |item, index|
+          invalid!('validation/invalid-type', "metadata.#{index}") unless item.is_a?(Hash)
+          invalid!('validation/invalid-type', "metadata.#{index}.id") unless item['id'].is_a?(String)
+          invalid!('validation/invalid-value', "metadata.#{index}.value") unless item.key?('value')
+        end
+      end
+
+      # Like the API's schema, checked before the asset is looked up: asset updates take no null
+      # name, and signed URLs no null field.
+      def check_asset_body(method, action, json)
+        case [method, action]
+        in ['PATCH', nil]
+          check_metadata(json['metadata'])
+          invalid!('validation/invalid-type', 'name') if json.key?('name') && json['name'].nil?
+        in ['POST', 'signed-url']
+          %w[viewerClaims resource lens transform expiresInSeconds].each do |key|
+            next unless json.key?(key) && json[key].nil?
+
+            invalid!(key == 'resource' ? 'validation/invalid-value' : 'validation/invalid-type', key)
+          end
+        else nil
+        end
+      end
+
+      # Like the API: an upload's metadata is checked, then its MIME type, which must be one the
+      # API can moderate (`upload/invalid-mime-type` with `details.mimeType`).
+      def check_upload(options)
+        check_metadata(options['metadata'])
+        type = options['contentType']
+        return if type.nil? || Internal.accepted_upload_mime_type?(type)
+
+        fail!(ErrorCodes::INVALID_UPLOAD_MIME_TYPE, "#{type} is not a valid upload file type",
+              details: { 'mimeType' => type })
+      end
+
       # Like the API's query schema: an integer from 1 to `max`.
       def check_range(value, path, max)
         invalid!('validation/too-small', path) if !value.is_a?(Numeric) || value < 1
@@ -253,10 +294,11 @@ module CalmLens
         parts = uri.path.split('/').reject(&:empty?).map { |part| URI.decode_www_form_component(part) }
         query = URI.decode_www_form(uri.query.to_s).to_h.to_h { |key, value| [key, query_value(key, value)] }
         content_type = header(headers, 'Content-Type')
-        json = content_type == 'application/json' && body ? JSON.parse(body) : {}
+        upload = header(headers, 'X-CalmLens-Upload')
+        # A raw upload's body is the file itself, whatever its type.
+        json = content_type == 'application/json' && body && upload.nil? ? JSON.parse(body) : {}
         # HTTP stacks trim header values, so the API sees the key without surrounding whitespace.
         key = header(headers, 'Idempotency-Key')&.to_s&.gsub(/\A[ \t\r\n]+|[ \t\r\n]+\z/, '')
-        upload = header(headers, 'X-CalmLens-Upload')
         return dispatch(method, parts, query, json, body, upload) unless key && method == 'POST'
 
         fail!(ErrorCodes::INVALID_IDEMPOTENCY_KEY) unless key.match?(IDEMPOTENCY_KEY)
@@ -507,6 +549,7 @@ module CalmLens
       end
 
       def create_asset(options, queue, url: nil, data: nil, open: false)
+        check_upload(options)
         check_folder(options['folderId']) if options['folderId']
         if options['externalId'] && project_assets.any? { |item| item['externalId'] == options['externalId'] }
           fail!(ErrorCodes::DUPLICATE_EXTERNAL_ID)
@@ -567,6 +610,7 @@ module CalmLens
       # In the API's order: a declared total, then a single final part as the whole upload, then the
       # part itself. The queue mode and declared total are saved with an open upload.
       def start_multipart(query, data)
+        check_upload(query)
         total = query['totalSizeInBytes']
         type = kind(query['contentType'].to_s, nil)
         final = query['isFinal'] == true
@@ -705,6 +749,7 @@ module CalmLens
 
       def asset(method, parts, query, json, body)
         id = parts[1]
+        check_asset_body(method, parts[2], json)
         item = @state.assets[id]
         fail!(ErrorCodes::ASSET_NOT_FOUND) unless item && item['projectId'] == @project_id
         case [method, parts[2]]
@@ -887,9 +932,9 @@ module CalmLens
         touch(item.merge!('parentId' => parent_id))
       end
 
-      # Policies: the project starts on its General preset policy, following automatic updates. The
-      # mock holds no built-in preset settings: a preset's settings are `{ 'categorySettings' => {} }`
-      # at version 1, and uploads are never decided by a policy.
+      # Policies: the project starts on the organisation's own General preset policy, following
+      # automatic updates. The mock holds no built-in preset settings: a preset's settings are
+      # `{ 'categorySettings' => {} }` at version 1, and uploads are never decided by a policy.
       def new_policy(name, settings, description: '', automatic_updates: false, preset: nil)
         now = @now.call
         item = { 'id' => @create_id.call('pol'), 'name' => name, 'description' => description, 'settings' => settings,
@@ -901,7 +946,7 @@ module CalmLens
       def ensure_policies
         return if @project_policy_id
 
-        preset = { 'id' => 'general-community', 'version' => 1, 'projectId' => @project_id }
+        preset = { 'id' => 'general-community', 'version' => 1, 'own' => true }
         @project_policy_id = new_policy(PRESET_NAMES['general-community'], { 'categorySettings' => {} },
                                         automatic_updates: true, preset: preset)['id']
       end
@@ -932,7 +977,7 @@ module CalmLens
         end
         description = json['description'].is_a?(String) ? json['description'] : ''
         item = if preset_id
-                 origin = { 'id' => preset_id, 'version' => 1, 'projectId' => nil }
+                 origin = { 'id' => preset_id, 'version' => 1, 'own' => false }
                  new_policy(named ? name.strip : PRESET_NAMES[preset_id], { 'categorySettings' => {} },
                             description: description, preset: origin)
                else
@@ -992,9 +1037,7 @@ module CalmLens
       def set_policy_automatic_updates(item, json)
         enabled = json['enabled'] == true
         preset = item['preset']
-        if preset.nil? || preset['projectId'] != @project_id || item['automaticUpdates'] == enabled
-          fail!(ErrorCodes::POLICY_AUTOMATIC_UPDATES_UNAVAILABLE)
-        end
+        fail!(ErrorCodes::POLICY_AUTOMATIC_UPDATES_UNAVAILABLE) if preset.nil? || !preset['own'] || item['automaticUpdates'] == enabled
         fail!(ErrorCodes::POLICY_REVISION_CONFLICT) unless json['revision'] == item['revision']
         fail!(ErrorCodes::POLICY_PRESET_VERSION_CONFLICT) unless json['presetVersion'] == 1
 
@@ -1168,13 +1211,27 @@ module CalmLens
       # private asset needs an API key with `assets:download` for its folder.
       def serve(method, relative)
         path, query = relative.split('#', 2).first.split('?', 2)
-        segments = path.split('/').reject(&:empty?).map { |part| URI.decode_www_form_component(part) }
-        _, project, identifier, resource = segments
+        raw_segments = path.split('/').reject(&:empty?)
+        _, project, identifier, resource = raw_segments.map { |part| URI.decode_www_form_component(part) }
+        # Like the CDN, the selector after the resource is read first, and lenses and transforms
+        # apply only to the rendered resource.
+        begin
+          lens, options = TransformRules.parse_selector(raw_segments.drop(4).join('/'))
+        rescue ArgumentError
+          return invalid_transform
+        end
+        return invalid_transform if resource == 'original' && (lens || options)
+
         item = project == @project_id && project_assets.find { |asset| [asset['id'], asset['externalId']].include?(identifier) }
         return error('asset/not-found', 'Asset not found', status: 404) unless item && RESOURCES.include?(resource)
-
         return placeholder(method, item) if resource == 'placeholder'
 
+        deliver(method, item, URI.decode_www_form(query.to_s).to_h, options)
+      end
+
+      # Serves a found asset's content after the delivery, age and access checks, then the
+      # transform options' schema check.
+      def deliver(method, item, params, options)
         moderation = item['classification']['moderation']['status']
         stored = @state.content[item['id']]
         if stored.nil? || item['upload']['status'] == 'uploading' || %w[blocked purged].include?(moderation) ||
@@ -1182,9 +1239,7 @@ module CalmLens
           return not_available
         end
 
-        params = URI.decode_www_form(query.to_s).to_h
-        opted_in = viewer_age_confirmed?(params)
-        if moderation == 'age-restricted' && !opted_in
+        if moderation == 'age-restricted' && !viewer_age_confirmed?(params)
           return error('viewer/age-confirmation-required', 'Age confirmation required',
                        status: 403)
         end
@@ -1195,6 +1250,9 @@ module CalmLens
                        'This API key needs assets:download permission for this asset’s folder.', status: 403)
         end
 
+        refused = options ? TransformRules.check(options).flatten : []
+        return error('asset/invalid-transform-options', "Invalid transform options: #{refused.join(', ')}", status: 400) if refused.any?
+
         type = stored['type'].to_s.empty? ? 'application/octet-stream' : stored['type']
         cdn_response(method, stored['parts'].sort.map(&:last).join.b,
                      viewer_delivery_headers(item, type, restricted, params))
@@ -1210,6 +1268,8 @@ module CalmLens
         headers
       end
 
+      def invalid_transform = error('asset/invalid-transform', 'Invalid transform selector', status: 400)
+
       def not_available = error('asset/not-available', 'Asset is not available', status: 403)
 
       # Like the CDN's placeholder handler: an image's ThumbHash, public whatever the asset's

data/lib/calmlens/testing/test_inputs.rb

@@ -82,7 +82,8 @@ module CalmLens
                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 'violence.graphic'
+                 { 'instances' => [{ 'category' => 'violence', 'qualifiers' => %w[violence-injury violence-graphic] }] }
                when *MockClassification::CATEGORIES then { 'instances' => [{ 'category' => signal, 'qualifiers' => [] }] }
                else raise Internal.invalid("Unknown test signal #{signal.inspect}")
                end

data/lib/calmlens/testing.rb

@@ -128,7 +128,7 @@ module CalmLens
       -> { lock.synchronize { last = [(Time.now.to_f * 1000).to_i, last + 1].max } }
     end
 
-    # @param project_id [String]
+    # @param project_id [String] `project-1` by default.
     # @param api_key [String] a key from {.create_api_key}; the default has no grants.
     # @param now [#call] returns the current time in epoch milliseconds. The default clock reads the
     #   system time but advances at least 1 ms per reading, so records made in a row have strictly
@@ -228,6 +228,9 @@ module CalmLens
         raise Internal.invalid('retry_after must be a whole number of seconds')
       end
       raise Internal.invalid('details must be a Hash') unless details.nil? || details.is_a?(Hash)
+      if !(failure.is_a?(String) && ErrorCodes::STATUSES.key?(failure)) && !(details.nil? && retry_after.nil?)
+        raise Internal.invalid('details and retry_after apply only to an API error code')
+      end
 
       name = operation && operation.to_s.split('.').map { |part| Internal.camelize(part) }.join('.')
       if name && !OPERATION_NAMES.include?(name)

data/lib/calmlens/transform_rules.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # The CDN's rules for transforms: options checked against the image transform schema
+  # (Internal::TRANSFORM_OPTIONS_SCHEMA), and selectors read as the CDN reads them.
+  # @api private
+  module TransformRules
+    module_function
+
+    # Checks transform options against the image transform schema, as the CDN does, and returns
+    # the dotted keys it doesn't know and those whose values it refuses (or that are required and
+    # missing). nil options are left out of a selector, so they are not checked.
+    # @return [Array(Array<String>, Array<String>)] the unknown keys and the invalid keys
+    def check(options)
+      unknown = []
+      invalid = []
+      check_rule(Internal::TRANSFORM_OPTIONS_SCHEMA, options, '', unknown, invalid)
+      [unknown, invalid]
+    end
+
+    def check_rule(schema, value, key, unknown, invalid)
+      rule = schema.key?('oneOf') ? schema['oneOf'].find { |branch| rule_type?(branch['type'], value) } : schema
+      return invalid << key unless rule && rule_allows?(rule, value)
+      return unless rule['type'] == 'object'
+
+      path = ->(name) { key.empty? ? name : "#{key}.#{name}" }
+      entries = value.to_h { |name, item| [name.to_s, item] }
+      rule.fetch('required', []).each { |name| invalid << path.call(name) if entries[name].nil? }
+      entries.keys.sort.each do |name|
+        next if entries[name].nil?
+
+        child = rule.fetch('properties', {})[name]
+        child ? check_rule(child, entries[name], path.call(name), unknown, invalid) : unknown << path.call(name)
+      end
+    end
+
+    def rule_allows?(rule, value)
+      rule_type?(rule['type'], value) &&
+        (!rule.key?('enum') || rule['enum'].include?(value)) &&
+        (!rule.key?('minimum') || value >= rule['minimum']) &&
+        (!rule.key?('maximum') || value <= rule['maximum'])
+    end
+
+    def rule_type?(type, value)
+      case type
+      when 'object' then value.is_a?(Hash)
+      when 'string' then value.is_a?(String)
+      when 'boolean' then [true, false].include?(value)
+      when 'number' then value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+      when 'integer' then value.is_a?(Integer) || (value.is_a?(Float) && value.finite? && value == value.floor)
+      else true
+      end
+    end
+
+    NUMBER = /\A-?(?:0|[1-9]\d*)(?:\.\d+)?\z/
+    LENS = /\A[a-z0-9-]{1,50}\z/
+
+    # Reads a CDN selector, the path text after the resource as sent (still percent-encoded), as the
+    # CDN does: an optional first `@lens`, then `key=value` options with dotted keys for nested ones (a
+    # bare key is `true`). Values are numbers, `true`, `false`, hex colours (`#` added) for colour
+    # options, or text. Raises ArgumentError on anything the CDN refuses as `asset/invalid-transform`.
+    # Used by the mock CDN.
+    # @return [Array(String, Hash)] the lens and the options, each nil when absent
+    def parse_selector(selector)
+      return [nil, nil] if selector.empty?
+      raise ArgumentError, "Invalid transform selector #{selector.inspect}" if selector.include?('/')
+
+      entries = selector.split(',', -1)
+      lens = nil
+      if entries.first.start_with?('@')
+        lens = selector_text(entries.shift.delete_prefix('@'), selector)
+        raise ArgumentError, "Invalid transform selector #{selector.inspect}" unless lens.match?(LENS)
+      end
+      return [lens, nil] if entries.empty?
+
+      options = {}
+      entries.each { |entry| add_selector_entry(options, entry, selector) }
+      [lens, options]
+    end
+
+    def add_selector_entry(options, entry, selector)
+      fail = -> { ArgumentError.new("Invalid transform selector #{selector.inspect}") }
+      raise fail.call if entry.empty? || entry.start_with?('@')
+
+      key, separator, text = entry.partition('=')
+      parts = key.split('.', -1)
+      raise fail.call unless parts.all? { |part| part.match?(Transforms::OPTION_NAME) }
+
+      value = separator.empty? || selector_value(key, selector_text(text, selector))
+      raise fail.call if value == ''
+
+      target = parts[0..-2].reduce(options) do |current, part|
+        raise fail.call unless current[part].nil? || current[part].is_a?(Hash)
+
+        current[part] ||= {}
+      end
+      raise fail.call if target.key?(parts.last)
+
+      target[parts.last] = value
+    end
+
+    def selector_value(key, text)
+      return text if text.empty?
+      return "##{text.downcase}" if Transforms::COLOUR_KEYS.include?(key) && Transforms::HEX_COLOUR.match?("##{text}")
+      return text.include?('.') ? Float(text) : Integer(text, 10) if text.match?(NUMBER)
+      return text == 'true' if %w[true false].include?(text)
+
+      text
+    end
+
+    # Percent-decodes selector text, refusing malformed escapes and text that isn't UTF-8.
+    def selector_text(text, selector)
+      decoded = text.b.gsub(/%(\h\h)/n) { Regexp.last_match(1).hex.chr }.force_encoding(Encoding::UTF_8)
+      raise ArgumentError, "Invalid transform selector #{selector.inspect}" if text.match?(/%(?!\h\h)/) || !decoded.valid_encoding?
+
+      decoded
+    end
+  end
+  private_constant :TransformRules
+end

data/lib/calmlens/transform_schema.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/generate.ts from IMAGE_TRANSFORM_OPTIONS_SCHEMA; do not edit.
+# The rules each transform option is checked against; see packages/sdk-contract/README.md.
+
+require 'json'
+
+module CalmLens
+  module Internal
+    # The image transform options' schema, with only the rules the SDK checks.
+    TRANSFORM_OPTIONS_SCHEMA = JSON.parse(<<~JSON).freeze
+      {
+        "type": "object",
+        "properties": {
+          "format": {
+            "type": "string",
+            "enum": [
+              "jpg",
+              "png",
+              "webp",
+              "avif",
+              "gif"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10000
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10000
+          },
+          "dpr": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 3
+          },
+          "anim": {
+            "type": "boolean"
+          },
+          "background": {
+            "type": "string"
+          },
+          "blur": {
+            "type": "number"
+          },
+          "redact": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "type": "boolean"
+              },
+              "personalInformation": {
+                "type": "boolean"
+              },
+              "faces": {
+                "type": "boolean"
+              }
+            }
+          },
+          "border": {
+            "type": "object",
+            "properties": {
+              "color": {
+                "type": "string"
+              },
+              "width": {
+                "type": "number"
+              }
+            }
+          },
+          "brightness": {
+            "type": "number"
+          },
+          "contrast": {
+            "type": "number"
+          },
+          "quality": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              }
+            ]
+          },
+          "fit": {
+            "type": "string",
+            "enum": [
+              "scale-down",
+              "contain",
+              "pad",
+              "squeeze",
+              "cover",
+              "crop"
+            ]
+          },
+          "flip": {
+            "type": "string",
+            "enum": [
+              "h",
+              "v",
+              "hv"
+            ]
+          },
+          "gamma": {
+            "type": "number"
+          },
+          "segment": {
+            "type": "string",
+            "enum": [
+              "foreground"
+            ]
+          },
+          "gravity": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "face",
+                  "left",
+                  "right",
+                  "top",
+                  "bottom",
+                  "center",
+                  "auto",
+                  "entropy"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "remainder",
+                      "box-center"
+                    ]
+                  },
+                  "x": {
+                    "type": "number"
+                  },
+                  "y": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            ]
+          },
+          "rotate": {
+            "type": "integer",
+            "enum": [
+              0,
+              90,
+              180,
+              270
+            ]
+          },
+          "saturation": {
+            "type": "number"
+          },
+          "sharpen": {
+            "type": "number"
+          },
+          "trim": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "border"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "top": {
+                    "type": "number"
+                  },
+                  "bottom": {
+                    "type": "number"
+                  },
+                  "left": {
+                    "type": "number"
+                  },
+                  "right": {
+                    "type": "number"
+                  },
+                  "width": {
+                    "type": "number"
+                  },
+                  "height": {
+                    "type": "number"
+                  },
+                  "border": {
+                    "oneOf": [
+                      {
+                        "type": "boolean"
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "color": {
+                            "type": "string"
+                          },
+                          "tolerance": {
+                            "type": "number"
+                          },
+                          "keep": {
+                            "type": "number"
+                          }
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    JSON
+  end
+end

data/lib/calmlens/transforms.rb

@@ -42,6 +42,7 @@ module CalmLens
     def serialize(value)
       raise Internal.invalid('Transform options must be a Hash') unless value.is_a?(Hash)
 
+      assert_valid(value)
       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?
@@ -49,6 +50,21 @@ module CalmLens
       pairs.join(',')
     end
 
+    # Raises `sdk/invalid-argument` naming each transform option the CDN would refuse, with
+    # `details` `{'unknownKeys', 'invalidKeys'}`.
+    def assert_valid(options)
+      unknown, invalid = TransformRules.check(options)
+      return if unknown.empty? && invalid.empty?
+
+      problems = []
+      problems << "unknown option#{'s' if unknown.size > 1} #{unknown.join(', ')}" unless unknown.empty?
+      problems << "invalid value#{'s' if invalid.size > 1} for #{invalid.join(', ')}" unless invalid.empty?
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT,
+                                     "Transform options are invalid: #{problems.join('; ')}. Pass the options " \
+                                     "themselves, such as { width: 640, format: 'webp' }.",
+                                     details: { 'unknownKeys' => unknown, 'invalidKeys' => invalid })
+    end
+
     def sorted_options(options, prefix = '')
       options.map do |key, item|
         name = key.to_s

data/lib/calmlens/upload_mime_types.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/generate.ts from packages/shared/src/UploadMimeTypes.ts; do not edit.
+# After lower-casing and dropping parameters, a type in REJECTED is refused; otherwise one
+# that starts with a PREFIXES entry, ends with a SUFFIXES entry or is in TYPES is accepted,
+# and any other type is refused with upload/invalid-mime-type.
+
+module CalmLens
+  module Internal
+    UPLOAD_MIME_REJECTED = [
+      'application/octet-stream',
+      'multipart/form-data',
+      'multipart/mixed',
+      'multipart/alternative',
+      'multipart/related',
+      'multipart/signed',
+      'multipart/encrypted'
+    ].freeze
+    UPLOAD_MIME_PREFIXES = [
+      'image/',
+      'video/',
+      'audio/',
+      'text/'
+    ].freeze
+    UPLOAD_MIME_SUFFIXES = [
+      '+json',
+      '+xml'
+    ].freeze
+    UPLOAD_MIME_TYPES = [
+      'application/pdf',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      'application/msword',
+      'application/rtf',
+      'application/vnd.oasis.opendocument.text',
+      'application/javascript',
+      'application/json',
+      'application/x-javascript',
+      'application/x-yaml',
+      'application/xml',
+      'application/yaml'
+    ].freeze
+  end
+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.19.0'
+  VERSION = '0.20.0'
 end

data/lib/calmlens.rb

@@ -9,8 +9,11 @@ require_relative 'calmlens/version'
 require_relative 'calmlens/error_codes'
 require_relative 'calmlens/errors'
 require_relative 'calmlens/option_keys'
+require_relative 'calmlens/transform_schema'
+require_relative 'calmlens/upload_mime_types'
 require_relative 'calmlens/internal'
 require_relative 'calmlens/transforms'
+require_relative 'calmlens/transform_rules'
 require_relative 'calmlens/response'
 require_relative 'calmlens/transport'
 require_relative 'calmlens/upload_body'

data/sig/calmlens.rbs

@@ -357,7 +357,8 @@ module CalmLens
     # Replaces the mock API key's grants for later requests; the key stays the same.
     def api_key_grants=: (Array[Hash[Symbol | String, untyped]] grants) -> Array[Hash[Symbol | String, untyped]]
     # Fails the next request (or the next one `operation` sends) with `transport-error`, `timeout`, an
-    # API error code (with optional `details` and `Retry-After` seconds) or an exception.
+    # API error code (with optional `details` and `Retry-After` seconds, which only an API error takes) or
+    # an exception.
     def fail_next_request: (?(String | Exception) failure, ?operation: String?, ?details: Hash[String | Symbol, untyped]?,
                             ?retry_after: Integer?) -> self
     def state: () -> Testing::State

data/sig/types.rbs

@@ -639,12 +639,14 @@ module CalmLens
     ?"linkSafety" => link_safety_settings
   }
   # Where a policy started from a built-in preset. `version` is the release it is pinned to,
-  # `latestVersion` the newest; `projectId` is the project whose preset policy it is, or nil for a copy.
+  # `latestVersion` the newest; `own` is whether this is the organisation's own policy for the preset
+  # rather than a copy made from it. An organisation has at most one per preset, and only it can
+  # follow automatic updates.
   type policy_preset_origin = {
     "id" => policy_preset_id,
     "version" => Integer,
     "latestVersion" => Integer,
-    "projectId" => String?
+    "own" => bool
   }
   # A moderation policy. Policies belong to the project's organisation and its projects share them.
   # Send `revision` with each change; a policy changed since is refused with `policy/revision-conflict`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - CalmLens
@@ -45,9 +45,12 @@ files:
 - lib/calmlens/testing/test_input_scenario.rb
 - lib/calmlens/testing/test_inputs.rb
 - lib/calmlens/text.rb
+- lib/calmlens/transform_rules.rb
+- lib/calmlens/transform_schema.rb
 - lib/calmlens/transforms.rb
 - lib/calmlens/transport.rb
 - lib/calmlens/upload_body.rb
+- lib/calmlens/upload_mime_types.rb
 - lib/calmlens/upload_tokens.rb
 - lib/calmlens/version.rb
 - lib/calmlens/webhooks.rb