calmlens 0.18.3 → 0.20.0

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,55 @@ 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?
+      raise Internal.invalid('Transform options must be a Hash') unless value.is_a?(Hash)
 
-      steps.map do |step|
-        raise Internal.invalid('Transform steps must be Hashes') unless step.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?
 
-        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)
-
-        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.join(',')
+    end
 
-        pairs.join(',')
-      end.join('/')
+    # 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 = '')

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_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/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.3'
+  VERSION = '0.20.0'
 end

data/lib/calmlens.rb

@@ -8,8 +8,12 @@ end
 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'
@@ -19,6 +23,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'

data/sig/calmlens.rbs

@@ -109,10 +109,14 @@ module CalmLens
     RETRY_MAX_DELAY: Integer
     RETRY_AFTER_MAX: Integer
     DEFAULT_MAX_RESPONSE_BYTES: Integer
+    DEFAULT_PART_SIZE_BYTES: Integer
+    MIN_PART_SIZE_BYTES: Integer
+    MAX_PART_SIZE_BYTES: Integer
     ENSURE_LENSES_MAX_PER_REQUEST: Integer
     attr_reader assets: Assets
     attr_reader folders: Folders
     attr_reader hash_lists: HashLists
+    attr_reader policies: Policies
     attr_reader text: Text
     attr_reader upload_tokens: UploadTokens
     attr_reader events: Events
@@ -122,7 +126,7 @@ module CalmLens
     attr_reader cdn_base_url: String
     def initialize: (api_key: String, project_id: String, ?base_url: String, ?cdn_base_url: String, ?timeout: number,
                      ?open_timeout: number, ?upload_timeout: number?, ?max_retries: Integer, ?retry_base_delay: number,
-                     ?max_response_bytes: Integer, ?transport: Transport::_Transport?) -> void
+                     ?max_response_bytes: Integer, ?part_size_bytes: Integer, ?transport: Transport::_Transport?) -> void
     def close: () -> nil
     def ensure_lenses: (ensure_lenses_options options) -> Array[lens]
     def ensure_lens: (ensure_lens_options options) -> lens
@@ -200,6 +204,17 @@ module CalmLens
     def remove_entry: (hash_list_entry_id_options options) -> nil
   end
 
+  class Policies < Resource
+    def list: (?list_policies_options options) -> policy_list
+    def retrieve: (policy_id_options options) -> policy
+    def create: (create_policy_options options) -> policy
+    def update: (update_policy_options options) -> policy
+    def apply_preset: (apply_policy_preset_options options) -> policy
+    def set_automatic_updates: (set_policy_automatic_updates_options options) -> policy
+    def delete: (policy_id_options options) -> nil
+    def assign: (assign_policy_options options) -> policy
+  end
+
   class UploadTokens < Resource
     TOKEN_PREFIX: String
     SIGNING_CONTEXT: String
@@ -338,11 +353,12 @@ module CalmLens
     def initialize: (?project_id: String, ?api_key: String, ?base_url: String, ?cdn_base_url: String, ?now: _Clock, ?create_id: _IdFactory,
                      ?moderate: _Moderate?, ?timeout: number,
                      ?open_timeout: number, ?upload_timeout: number?, ?max_retries: Integer, ?retry_base_delay: number,
-                     ?max_response_bytes: Integer) -> void
+                     ?max_response_bytes: Integer, ?part_size_bytes: Integer) -> void
     # 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
@@ -398,5 +414,45 @@ module CalmLens
   module MockClassification
     CATEGORIES: Array[String]
     QUALIFIERS: Hash[String, Array[String]]
+    # Qualifiers the input type sets, which a TestInputs scenario cannot list.
+    INPUT_QUALIFIERS: Array[String]
+  end
+
+  # Signed test inputs: text codes, test images and media phrases signed with a project's secret
+  # test input key from the portal.
+  module TestInputs
+    type action = "allow" | "limit" | "age-restrict" | "block"
+    type region = "DE" | "AT" | "FR" | "GB" | "EU" | "AU" | "BR"
+    type regional_action = { "region" => region, "action" => "limit" | "age-restrict" | "block" }
+    # One qualifying instance; set an action on every instance or on none.
+    type test_instance = { "category" => classification_category, ?"score" => number, ?"action" => action, "qualifiers" => Array[String] }
+    # A scenario with String keys; Symbol and snake_case keys are accepted as a plain Hash.
+    type scenario = { ?"regionalActions" => Array[regional_action], ?"unassessedCategories" => Array[classification_category],
+                      "instances" => Array[test_instance] }
+    type signal = classification_category | "sexual.involving-minors" | "harassment.insult" | "sexual.adult"
+                | "hate.regional-symbol" | "violence.graphic"
+    type media_signal = classification_category | "violence.graphic"
+    type input = scenario | Hash[String | Symbol, untyped] | signal
+
+    # A painted test image: width by height pixels of 8-bit RGBA in the binary String `rgba`, and
+    # the same image as binary PNG bytes in `png`.
+    class Image < Struct[untyped]
+      attr_accessor width: Integer
+      attr_accessor height: Integer
+      attr_accessor rgba: String
+      attr_accessor png: String
+      def initialize: (width: Integer, height: Integer, rgba: String, png: String) -> void
+    end
+
+    REGIONS: Array[region]
+    SIGNALS: Array[signal]
+    MEDIA_SIGNALS: Array[media_signal]
+    # clean, limited, adult_image, adult_text, regional_delivery, germany and mixed (deeply frozen).
+    PRESETS: Hash[Symbol, scenario]
+
+    def self.for_signal: (signal signal, ?("text" | "image") kind) -> scenario
+    def self.generate_text_code: (input input, String test_input_key) -> String
+    def self.paint_image: (input input, String test_input_key) -> Image
+    def self.generate_media_code: (media_signal signal, String test_input_key) -> String
   end
 end

data/sig/error_codes.rbs

@@ -7,6 +7,8 @@ module CalmLens
     INVALID_VIEWER_REGION: String
     VIEWER_REGION_REQUIRED: String
     REGIONAL_EVIDENCE_REQUIRED: String
+    SIGNED_URL_EXPIRED: String
+    SIGNED_URL_INVALID: String
     INVALID_TYPE: String
     TOO_SMALL: String
     TOO_BIG: String
@@ -34,9 +36,11 @@ module CalmLens
     API_KEY_NOT_ACCEPTED: String
     PERMISSION_DENIED: String
     FILE_TOO_LARGE: String
-    MULTIPART_IMAGE_TOO_SMALL: String
     MULTIPART_IMAGE_TOO_LARGE: String
     IMAGE_EXCEEDED_MAX_DIMENSIONS: String
+    IMAGE_INVALID_INPUT: String
+    IMAGE_UNSUPPORTED_FORMAT: String
+    IMAGE_INPUT_LIMIT: String
     UPLOAD_LIMIT_EXCEEDED: String
     SPEND_LIMIT_REACHED: String
     INVALID_UPLOAD_MIME_TYPE: String
@@ -77,6 +81,15 @@ module CalmLens
     HASH_LIST_LIMIT_REACHED: String
     HASH_LIST_ENTRY_LIMIT_REACHED: String
     HASH_LIST_ASSET_NOT_HASHED: String
+    POLICY_NOT_FOUND: String
+    POLICY_REVISION_CONFLICT: String
+    POLICY_PROJECTS_CHANGED: String
+    POLICY_IN_USE: String
+    POLICY_USED_BY_ANOTHER_PROJECT: String
+    POLICY_NO_PRESET: String
+    POLICY_PRESET_VERSION_CONFLICT: String
+    POLICY_PRESET_UPDATE_UNAVAILABLE: String
+    POLICY_AUTOMATIC_UPDATES_UNAVAILABLE: String
     UPLOAD_PRESET_NOT_FOUND: String
     UPLOAD_PRESET_DISABLED: String
     UPLOAD_PRESET_TOKEN_REQUIRED: String

data/sig/types.rbs

@@ -60,8 +60,8 @@ module CalmLens
   # Earlier posts to send, oldest first; only the posts CalmLens uses are sent.
   type moderation_context_input = { items: Array[moderation_context_item_input] }
 
-  # ProcessingFeatures.ts: optional analyses to run, keyed by feature. Every feature is off unless
-  # `enabled` is true.
+  # ProcessingFeatures.ts: optional analyses to run, keyed by feature. Link detection runs unless
+  # `enabled` is false; every other feature is off unless `enabled` is true.
   type processing_features_input = {
     ?ocr: { enabled: bool }?,
     ?person_detection: { enabled: bool }?,
@@ -308,21 +308,25 @@ module CalmLens
   # Link safety (preview, LinkSafety.ts).
   # What a link's destination is: `safe` when every reputation check passed, `adult` or `gambling`
   # from its domain's content categories, `phishing` or `malware` from a threat list or the domain's
-  # security risks, and `unresolved` when a short link could not be followed or a check failed.
+  # security risks, and `unresolved` when a short link or redirect chain could not be followed or a
+  # check failed. Every address on a link's way is checked, and the most severe verdict is the
+  # link's.
   type link_safety_verdict = "safe" | "adult" | "gambling" | "phishing" | "malware" | "unresolved"
   # The verdicts a policy can act on.
   type flagged_link_verdict = "phishing" | "malware" | "adult" | "gambling" | "unresolved"
   # What a link does to its asset, weakest first. Purging content over a link is never offered.
   type link_safety_action = "allow" | "limit" | "age-restrict" | "block"
-  # One reputation check of a link's destination: its domain's categories, or a threat-list lookup
-  # of the destination URL. `failed` makes the link `unresolved`; `labels` is what the check reported.
+  # One reputation check of a link, every address it redirects through and its destination: their
+  # domain categories, or a threat-list lookup of their URLs. `failed` makes the link `unresolved`;
+  # `labels` is what the check reported for any of the addresses.
   type link_safety_evidence = {
     "check" => "domain-categories" | "threat-lists",
     "status" => "checked" | "failed",
     "labels" => Array[String]
   }
   # A link in the asset and what its destination is. `finalUrl` is where it leads after `redirects`
-  # redirects, or `null` when a short link could not be followed.
+  # redirects, or `null` when a short link or redirect chain could not be
+  # followed.
   type checked_link = {
     "url" => String,
     "finalUrl" => String?,
@@ -450,7 +454,8 @@ module CalmLens
     ?blur: number,
     ?redact: {
       ?text: bool,
-      ?personalInformation: bool
+      ?personalInformation: bool,
+      ?faces: bool
     },
     ?border: {
       ?color: String,
@@ -496,7 +501,8 @@ module CalmLens
     ?"blur" => number,
     ?"redact" => {
       ?"text" => bool,
-      ?"personalInformation" => bool
+      ?"personalInformation" => bool,
+      ?"faces" => bool
     },
     ?"border" => {
       ?"color" => String,
@@ -533,12 +539,9 @@ module CalmLens
   }
   # </generated: image-transform-options>
 
-  # One structured transform step. `imageTransform` is the only transform type.
-  type transform_step_input = { type: "imageTransform", ?options: image_transform_options_input }
-  type transform_step = { "type" => "imageTransform", ?"options" => image_transform_options }
-  # A selector String with one step per path segment, such as `fit=cover,width=1024/blur=12`, or
-  # structured steps, which the SDK serializes into a selector.
-  type transform_input = String | transform_step_input | Array[transform_step_input]
+  # Transform options applied in one pass: a selector String such as `width=1024,fit=cover`, or
+  # structured options, which the SDK serializes into a selector.
+  type transform_input = String | image_transform_options_input
 
   type lens_type = "image" | "video" | "audio" | "document" | "website"
   # ENSURE_LENS_BODY_SCHEMA. Changing a saved lens needs a greater `version` (default 1).
@@ -549,7 +552,7 @@ module CalmLens
     active: bool,
     ?description: String?,
     ?version: Integer,
-    ?transforms: Array[transform_step_input]?
+    ?transform: image_transform_options_input?
   }
   type lens = {
     "id" => String,
@@ -560,7 +563,7 @@ module CalmLens
     ?"description" => String?,
     "type" => lens_type,
     "active" => bool,
-    ?"transforms" => Array[transform_step]?,
+    ?"transform" => image_transform_options?,
     "createdAt" => Integer,
     ?"updatedAt" => Integer
   }
@@ -619,6 +622,49 @@ module CalmLens
     "ordering" => Array[order]
   }
 
+  # ---- Policies (Policy.ts) ---------------------------------------------------------------------
+
+  type policy_preset_id = "general-community" | "children-platform" | "education-support" | "wholesome-community"
+  # What a policy does with one category: `action` when its policy score reaches 0.5 (default
+  # `block`), allowances that let covered content through or act on it more softly, and
+  # restrictions, which outweigh allowances.
+  type category_policy_settings = {
+    ?"action" => flagged_content_action,
+    ?"allowances" => Array[policy_rule_snapshot],
+    ?"restrictions" => Array[policy_rule_snapshot]
+  }
+  # Settings by category (`sexual`, `violence`, ...), and optionally link safety.
+  type policy_settings = {
+    "categorySettings" => Hash[String, category_policy_settings],
+    ?"linkSafety" => link_safety_settings
+  }
+  # Where a policy started from a built-in preset. `version` is the release it is pinned to,
+  # `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,
+    "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`.
+  type policy = {
+    "id" => String,
+    "name" => String,
+    "description" => String,
+    "settings" => policy_settings,
+    "revision" => Integer,
+    "automaticUpdates" => bool,
+    "preset" => policy_preset_origin?,
+    "projectIds" => Array[String],
+    "createdAt" => Integer,
+    "updatedAt" => Integer
+  }
+  # Every policy of the project's organisation, oldest first, and the one the project moderates with.
+  type policy_list = { "policies" => Array[policy], "projectPolicyId" => String }
+
   # ---- Events and webhooks (Event.ts, EventCatalog.ts, WebhookPayload.ts) ----------------------
 
   # EVENT_TYPES in EventCatalog.ts. Ignore types your code does not handle. Webhook, Slack and email
@@ -661,7 +707,14 @@ module CalmLens
     "createdAt" => Integer
   }
   # Unlike other lists, `nextCursor` is never nil: keep it to receive later events.
-  type events_page = { "items" => Array[event], "nextCursor" => String, "hasMore" => bool }
+  # `excludedTypes` are the event types the feed never includes, because the API key lacks the permission
+  # to see them.
+  type events_page = {
+    "items" => Array[event],
+    "nextCursor" => String,
+    "hasMore" => bool,
+    "excludedTypes" => Array[event_type]
+  }
 
   # ---- Method options -------------------------------------------------------------------------
 
@@ -720,7 +773,7 @@ module CalmLens
     # Defaults to `rendered` on the server; `original` takes no lens or transform.
     ?resource: "original" | "rendered",
     ?expires_in_seconds: Integer,
-    # A lens runs before any additional transforms.
+    # Transform options replace the lens's options of the same name.
     ?lens: String,
     ?transform: transform_input,
     ?request_options: request_options
@@ -859,6 +912,37 @@ module CalmLens
                                        ?request_options: request_options }
   type hash_list_entry_id_options = { entry_id: String, ?request_options: request_options }
 
+  # Policy settings as options: snake_case Symbol keys, or a policy's `settings` as the API returned it.
+  type policy_rule_input = { when: Array[String], action: flagged_content_action, ?name: String, ?match: "all", ?unless: Array[String] }
+  type category_policy_settings_input = {
+    ?action: flagged_content_action,
+    ?allowances: Array[policy_rule_input],
+    ?restrictions: Array[policy_rule_input]
+  }
+  type link_safety_settings_input = {
+    verdict_actions: Hash[String | Symbol, link_safety_action],
+    ?off_platform_links: { action: "limit" | "age-restrict" | "block", allowed_domains: Array[String] }
+  }
+  type policy_settings_input = policy_settings | {
+    category_settings: Hash[String | Symbol, category_policy_settings_input],
+    ?link_safety: link_safety_settings_input
+  }
+  type list_policies_options = { ?request_options: request_options }
+  type policy_id_options = { policy_id: String, ?request_options: request_options }
+  # Send `settings` (defining every category) with a `name`, or `preset_id` to copy the latest
+  # release of a built-in preset, named after it unless you give a `name`.
+  type create_policy_options = { ?name: String, ?description: String, ?settings: policy_settings_input,
+                                 ?preset_id: policy_preset_id, ?request_options: request_options }
+  type update_policy_options = { policy_id: String, revision: Integer, ?name: String, ?description: String,
+                                 ?settings: policy_settings_input, ?request_options: request_options }
+  # `reset` restores the pinned preset version (send `preset.version`); `update` moves an unchanged
+  # copy to the latest release (send `preset.latestVersion`).
+  type apply_policy_preset_options = { policy_id: String, operation: "reset" | "update", revision: Integer,
+                                       preset_version: Integer, ?request_options: request_options }
+  type set_policy_automatic_updates_options = { policy_id: String, enabled: bool, revision: Integer,
+                                                preset_version: Integer, ?request_options: request_options }
+  type assign_policy_options = { policy_id: String, ?request_options: request_options }
+
   # `page_size` is 1 to 100, default 50.
   type list_events_options = { ?cursor: String, ?page_size: Integer, ?request_options: request_options }
 
@@ -870,7 +954,7 @@ module CalmLens
     active: bool,
     ?description: String?,
     ?version: Integer,
-    ?transforms: Array[transform_step_input]?,
+    ?transform: image_transform_options_input?,
     ?request_options: request_options
   }
 
@@ -881,7 +965,7 @@ module CalmLens
     # `rendered` is the default. `original` takes no lens or transform; `placeholder` is a small blurred PNG
     # that takes no lens or transform.
     ?resource: "original" | "rendered" | "placeholder",
-    # A lens runs before any additional transforms.
+    # Transform options replace the lens's options of the same name.
     ?lens: String,
     ?transform: transform_input,
     # Appends `?ageConfirmed=true`, so a public `age-restricted` asset is served from this URL. Set it

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.18.3
+  version: 0.20.0
 platform: ruby
 authors:
 - CalmLens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies: []
 description: 'Server-side client for the CalmLens API: moderation, uploads, events,
   webhooks and CDN delivery.'
@@ -30,6 +30,8 @@ files:
 - lib/calmlens/internal.rb
 - lib/calmlens/lenses.rb
 - lib/calmlens/moderation_context.rb
+- lib/calmlens/option_keys.rb
+- lib/calmlens/policies.rb
 - lib/calmlens/resource.rb
 - lib/calmlens/response.rb
 - lib/calmlens/server_client.rb
@@ -39,10 +41,16 @@ files:
 - lib/calmlens/testing/fake_api.rb
 - lib/calmlens/testing/mock_decision.rb
 - lib/calmlens/testing/placeholder.rb
+- lib/calmlens/testing/test_image_grid.rb
+- 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