calmlens 0.22.0 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fd7cb8e811f68c6be7989deb980a259d4a5643bc6f4402324c64236d258661b
-  data.tar.gz: f5e03fc720335e9c2ee2116549ddad9407a627449aed230f31eacf9a31743a3d
+  metadata.gz: 0707eda417af2a9021104b813fecc82ca3a4cddbcc420d92fcd22642f844d61f
+  data.tar.gz: c834ec6d48c5815e93d1af413efbd2c8cab0b4fb67071d2da17ac9d97ffab018
 SHA512:
-  metadata.gz: ea06ee7b551c7e4a4336f3fb972e0e1181a55b5a148cb89c3b281dff789efe60289db280c18ffe700f1e883f763be60b10560b6a8321773c776aa40df2c57c13
-  data.tar.gz: b50571100307aaa792130cf4ca1d980232185613d9376a244b7857a7f052e0e43ffcbaa584fa661e869d349c3971e9d5199a07ac053844ee3ddbaa496db5aa81
+  metadata.gz: cfa54ba17a0a73abea37f1b34a76df43a2172ffa93e6801f0ae1cd671b40970516675fdcca7014fed69a8acf686a542f78e101fc7000580cc1c11f31c07ac095
+  data.tar.gz: 71a628e67b7887807d5c241913b4125836bf5493b6bb54558d9321bb47a4331ea54079dd94d4161dcb02dcc79c798d5653bd891f9c1b3ff3d8848f7cebac9bbd

data/lib/calmlens/assets.rb

@@ -310,7 +310,8 @@ module CalmLens
     end
 
     # Uploads content and waits for the moderation decision where the content type supports it.
-    # Audio and video are always processed asynchronously. Takes the options of {#create}.
+    # Documents, websites, audio, video and files over 20 MiB sent in parts always finish in the
+    # background and return `pending`. Takes the options of {#create}.
     # @return [Hash] the asset; show it to everyone only when `classification.moderation.status` is
     #   `allowed` or `limited` (reduce the reach of `limited` assets). Serve `age-restricted` assets
     #   only behind your own age check, through signed URLs.
@@ -358,24 +359,31 @@ module CalmLens
     def poll_for_decision(asset_id, request_options, timeout)
       deadline = @session.monotonic + timeout
       delay = DECISION_POLL_FIRST_DELAY
+      processing = moderation = nil
       loop do
-        asset = retrieve('assetId' => asset_id, 'request_options' => request_options)
+        remaining = deadline - @session.monotonic
+        break if timeout.positive? && !remaining.positive?
+
+        # The outer deadline covers transport retries and the entire response read.
+        asset = ::Timeout.timeout(timeout.zero? ? nil : remaining) do
+          retrieve('assetId' => asset_id, 'request_options' => request_options)
+        end
+        remaining = deadline - @session.monotonic
+        break if timeout.positive? && !remaining.positive?
+
         processing = asset.dig('classification', 'status')
         moderation = asset.dig('classification', 'moderation', 'status')
         return asset if SETTLED_STATUSES.include?(processing)
-
-        remaining = deadline - @session.monotonic
-        unless remaining.positive?
-          raise TimeoutError.new(SdkErrorCodes::TIMEOUT,
-                                 "Asset #{asset['id']} was not settled after #{timeout}s " \
-                                 "(processing #{processing}, moderation #{moderation})",
-                                 details: { 'assetId' => asset['id'], 'classificationStatus' => processing,
-                                            'moderationStatus' => moderation })
-        end
+        break unless remaining.positive?
 
         sleep([delay, remaining].min)
         delay = [delay * DECISION_POLL_FACTOR, DECISION_POLL_MAX_DELAY].min
       end
+      raise ::Timeout::Error
+    rescue ::Timeout::Error
+      raise TimeoutError.new(SdkErrorCodes::TIMEOUT, "Asset #{asset_id} was not settled after #{timeout}s",
+                             details: { 'assetId' => asset_id, 'classificationStatus' => processing,
+                                        'moderationStatus' => moderation })
     end
 
     def submit(options, request_options, wait)

data/lib/calmlens/cdn.rb

@@ -53,7 +53,7 @@ module CalmLens
     # @option options [String] :resource `rendered` (the displayable file: an image in the best format the
     #   client accepts, a PDF, or browser-safe video or audio), `original` (the exact upload), `preview` (a
     #   still image for the asset), `hls` (the HLS master playlist of audio or video, at `hls/index.m3u8`,
-    #   once `content.hls` is set), `embed` (an HTML page that shows the asset, a viewer for its type, for an
+    #   once `content.hls.status` is `ready`), `embed` (an HTML page that shows the asset, a viewer for its type, for an
     #   iframe), `placeholder` (a small blurred PNG that the CDN serves publicly for every asset whatever its
     #   visibility or moderation status, without age confirmation) or `info` (the asset's display info, as
     #   {#get_asset_info} reads it). Without it, the URL is the asset URL itself. Lenses and transforms
@@ -69,7 +69,7 @@ module CalmLens
     #   alpha-2 country. The CDN serves an asset whose moderation status is `age-restricted` only with
     #   `age_confirmed: true`, even with a signed URL or the API key. Set it only where your app has
     #   already decided the viewer may see age-restricted content. Your platform confirms the viewer's
-    #   age; CalmLens does not verify this claim, and anyone can add it to a URL.
+    #   age; viewer claims are assertions from your app, and CalmLens doesn't verify them.
     # @return [String]
     def get_asset_url(options)
       call(options, __method__) { |api, _request| asset_url(api) }

data/lib/calmlens/lenses.rb

@@ -35,7 +35,7 @@ module CalmLens
     # @option options [String] :identifier
     # @option options [String] :name
     # @option options [String] :type `image`
-    # @option options [Boolean] :active whether the CDN serves it
+    # @option options [Boolean] :active whether the CDN serves it; true by default
     # @option options [String, nil] :description
     # @option options [Hash, String, nil] :transform
     # @return [Hash] the lens

data/lib/calmlens/server_client.rb

@@ -134,7 +134,7 @@ module CalmLens
     # them. Definitions this client already saved are not sent again, and sending the same
     # definition again returns the lens unchanged. More than 100 new definitions are sent in
     # consecutive requests, in order. {#lenses} manages lenses one by one.
-    # @option options [Array<Hash>] :lenses `[{identifier:, name:, type:, active:, transform:, ...}]`
+    # @option options [Array<Hash>] :lenses `[{identifier:, name:, type:, transform:, ...}]`, each served unless `active: false`
     # @return [Array<Hash>] the saved lenses, in the given order.
     def ensure_lenses(options) = @lenses.ensure_lenses(options)
 

data/lib/calmlens/session.rb

@@ -180,11 +180,10 @@ module CalmLens
     private
 
     # The fields that identify a lens definition, as canonical JSON: an unset description or
-    # transform is the same definition as an explicit null.
+    # transform is the same definition as an explicit null, and an unset `active` as `true`.
     def lens_key(lens)
       fields = { 'identifier' => lens['identifier'], 'name' => lens['name'], 'description' => lens['description'],
-                 'type' => lens['type'], 'transform' => lens['transform'] }
-      fields['active'] = lens['active'] if lens.key?('active')
+                 'type' => lens['type'], 'transform' => lens['transform'], 'active' => lens.fetch('active', true) }
       JSON.generate(canonical(fields))
     end
 

data/lib/calmlens/testing/classification.rb

@@ -8,7 +8,7 @@ module CalmLens
 
     # Each category's qualifiers.
     QUALIFIERS = {
-      "sexual" => ["sexual-pornographic-media", "sexual-nudity", "sexual-activity", "sexual-explicit-language", "sexual-assault-media", "sexual-non-consensual", "sexual-intimate-image-abuse", "sexual-extreme", "sexual-strangulation", "sexual-incest", "sexual-minors", "sexual-solicitation", "sexual-paid", "sexual-adult-promotion", "sexual-revealing-clothing", "sexual-suggestive", "sexual-non-erotic-nudity", "sexual-text", "sexual-historical", "sexual-documentary", "sexual-educational", "sexual-discussion", "sexual-fictional", "sexual-support-prevention"].freeze,
+      "sexual" => ["sexual-pornographic-media", "sexual-nudity", "sexual-activity", "sexual-explicit-language", "sexual-assault-media", "sexual-non-consensual", "sexual-intimate-image-abuse", "sexual-extreme", "sexual-strangulation", "sexual-incest", "sexual-minors", "sexual-solicitation", "sexual-paid", "sexual-adult-promotion", "sexual-revealing-clothing", "sexual-suggestive", "sexual-non-erotic-nudity", "sexual-text", "sexual-historical", "sexual-documentary", "sexual-educational", "sexual-discussion", "sexual-fictional", "sexual-artistic", "sexual-support-prevention"].freeze,
       "violence" => ["violence-high-impact", "violence-attack", "violence-threat", "violence-preparation", "violence-encouragement", "violence-wish", "violence-coded-incitement", "violence-extremism", "violence-injury", "violence-violent-death", "violence-natural-death", "violence-graphic", "violence-decapitation-act", "violence-gore", "violence-weapon", "violence-sport", "violence-text", "violence-historical", "violence-documentary", "violence-educational", "violence-discussion", "violence-fictional", "violence-fantasy", "violence-support-prevention"].freeze,
       "self-harm" => ["self-harm-age-restricted", "self-harm-thoughts", "self-harm-preparation", "self-harm-act", "self-harm-methods", "self-harm-encouragement", "self-harm-historical", "self-harm-documentary", "self-harm-educational", "self-harm-fictional", "self-harm-support-prevention"].freeze,
       "harassment" => ["harassment-abuse", "harassment-mild", "harassment-bullying", "harassment-public-target", "harassment-threat", "harassment-sexual", "harassment-encouragement", "harassment-historical", "harassment-documentary", "harassment-educational", "harassment-fictional", "harassment-support-prevention"].freeze,

data/lib/calmlens/testing/fake_api.rb

@@ -81,7 +81,7 @@ module CalmLens
       # from its pixels. The `placeholder` resource serves it as a PNG, like the CDN.
       THUMBHASH = '1QcSHQRnh493V4dIh4eXh1h4kJUI'
       # Removing or withholding content removes its rendered file, adaptive stream and preview, as the API does.
-      NO_RENDERING = { 'rendered' => nil, 'hls' => nil, 'hlsStatus' => nil, 'preview' => nil }.freeze
+      NO_RENDERING = { 'rendered' => nil, 'hls' => nil, 'preview' => nil }.freeze
       # The size of the waveform the API makes as an audio asset's preview.
       WAVEFORM_SIZE = { 'width' => 1200, 'height' => 300 }.freeze
       # Audio and video formats browsers play as uploaded, so the API serves them as stored (Asset.ts).
@@ -272,6 +272,9 @@ module CalmLens
         # Like the API: a queued re-run no longer replaces a reviewed decision.
         @reruns.delete(item['id'])
         apply_outcome(item, decision, 'requested')
+        # Like the API: the human review queue's decision settles its review, one through the API
+        # leaves it waiting.
+        item['classification']['moderation']['pendingReview'] = nil unless by_api_key
         review = { 'id' => @create_id.call('rev'), 'decision' => decision, 'note' => note,
                    'decidedBy' => { 'type' => 'api-key', 'id' => nil }, 'reviewedAt' => @now.call, 'applied' => true }
         actor = by_api_key ? API_KEY_ACTOR : REVIEWER_ACTOR
@@ -613,6 +616,7 @@ module CalmLens
         old = @state.lenses[definition['identifier']]
         return new_lens(definition) unless old
 
+        definition = active_by_default(definition)
         same = %w[name type active].all? { |key| old[key] == definition[key] } &&
                old['description'] == definition['description'] && canonical(old['transform']) == canonical(definition['transform'])
         return old if same
@@ -622,10 +626,13 @@ module CalmLens
 
       def new_lens(definition)
         now = @now.call
-        lens = { 'id' => @create_id.call('lens'), 'projectId' => @project_id }.merge(definition)
+        lens = { 'id' => @create_id.call('lens'), 'projectId' => @project_id }.merge(active_by_default(definition))
         @state.lenses[definition['identifier']] = lens.merge('createdAt' => now, 'updatedAt' => now)
       end
 
+      # Like the API, a lens is served unless its definition says otherwise.
+      def active_by_default(definition) = definition['active'].nil? ? definition.merge('active' => true) : definition
+
       # POST /projects/:id/lenses: like the API, the identifier must be new to the project.
       def create_lens(json)
         identifier = json['identifier']
@@ -923,23 +930,70 @@ module CalmLens
 
         options, bytes = form_fields(body, request[:content_type])
         fields = options.merge('contentType' => query['contentType'])
-        return create_asset(fields, queue, data: bytes) if upload == 'content'
+        return create_asset(apply_upload_preset(fields, bytes), queue, data: bytes) if upload == 'content'
+
+        start_multipart(apply_upload_preset(fields.merge(query.slice('isFinal', 'totalSizeInBytes')), bytes), bytes, queue)
+      end
+
+      # An API-key upload through a preset, as the API applies it: the preset gives the folder and
+      # visibility, which the upload can't change, and the processing options unless the upload sets
+      # its own, and refuses types and sizes it doesn't accept.
+      def apply_upload_preset(fields, data = nil)
+        return fields unless fields['uploadPresetId']
+
+        preset = @upload_presets.values.find { |item| item['id'] == fields['uploadPresetId'] }
+        fail!(ErrorCodes::UPLOAD_PRESET_NOT_FOUND) unless preset
+        fail!(ErrorCodes::UPLOAD_PRESET_DISABLED) unless preset['enabled']
+        check_preset_fields(preset, fields)
+        check_preset_limits(preset, fields, data)
+        fields.merge('folderId' => preset['folderId'] || fields['folderId'], 'visibility' => preset['visibility'],
+                     'processingOptions' => fields['processingOptions'] || deep_copy(preset['processingOptions']))
+      end
+
+      def check_preset_fields(preset, fields)
+        if preset['folderId'] && fields['folderId'] && fields['folderId'] != preset['folderId']
+          fail!(ErrorCodes::UPLOAD_PRESET_FIELD_NOT_ALLOWED, details: { 'field' => 'folderId' })
+        end
+        return unless fields['visibility'] && fields['visibility'] != preset['visibility']
+
+        fail!(ErrorCodes::UPLOAD_PRESET_FIELD_NOT_ALLOWED, details: { 'field' => 'visibility' })
+      end
+
+      def check_preset_limits(preset, fields, data)
+        allowed = preset['allowedContentTypes']
+        type = fields['contentType']
+        if allowed && type && allowed.none? { |pattern| preset_accepts?(pattern, fields['name'], type) }
+          fail!(ErrorCodes::UNSUPPORTED_UPLOAD_TYPE,
+                details: { 'source' => 'preset', 'contentType' => type, 'allowedContentTypes' => allowed })
+        end
+        limit = preset['maxSizeInBytes']
+        size = fields['totalSizeInBytes'] || data&.bytesize
+        fail!(ErrorCodes::UPLOAD_TOO_LARGE, details: { 'limitBytes' => limit, 'source' => 'preset' }) if limit && size && size > limit
+      end
 
-        start_multipart(fields.merge(query.slice('isFinal', 'totalSizeInBytes')), bytes, queue)
+      # Whether an upload matches one entry of a preset's list, such as `image/*`, `text/plain` or `.pdf`.
+      def preset_accepts?(pattern, name, type)
+        pattern = pattern.strip.downcase
+        return true if ['*', '*/*'].include?(pattern)
+        return type.downcase.start_with?(pattern.delete_suffix('*')) if pattern.end_with?('/*')
+        return name.to_s.downcase.end_with?(pattern) if pattern.start_with?('.')
+
+        type.downcase == pattern
       end
 
       # A JSON create: text as `content` or a first `part` (`{ plainText, type }`), or a URL.
       def create_from_json(json, queue)
         key = %w[content part].find { |name| json.key?(name) }
-        return create_asset(json, queue, url: json['url']) unless key
+        return create_asset(apply_upload_preset(json), queue, url: json['url']) unless key
 
         text = json[key]
         invalid!('validation/invalid-type', key) unless text.is_a?(Hash) && text['plainText'].is_a?(String) && text['type'].is_a?(String)
         fields = json.except('content', 'part', 'sizeInBytes', 'totalSizeInBytes').merge('contentType' => text['type'])
         data = text['plainText'].encode(Encoding::UTF_8).b
-        return create_asset(fields, queue, data: data) if key == 'content'
+        return create_asset(apply_upload_preset(fields, data), queue, data: data) if key == 'content'
 
-        start_multipart(fields.merge('isFinal' => text['isFinal'] == true, 'totalSizeInBytes' => json['totalSizeInBytes']), data, queue)
+        part = fields.merge('isFinal' => text['isFinal'] == true, 'totalSizeInBytes' => json['totalSizeInBytes'])
+        start_multipart(apply_upload_preset(part, data), data, queue)
       end
 
       # The asset fields in an upload form's options part, and the file's bytes. Like the API, a raw
@@ -1023,7 +1077,7 @@ module CalmLens
       # faces in an image, so a decided image reports that the features its upload ran found nothing:
       # OCR and person and face detection when turned on, link detection unless turned off.
       def decided(asset, decision)
-        apply_outcome(asset, decision.status, 'policy', decision.report)
+        apply_outcome(asset, decision.status, 'policy', decision.report(@now.call))
         classification = asset['classification']
         return asset unless classification['status'] == 'completed' && asset['type'] == 'image'
 
@@ -1136,7 +1190,7 @@ module CalmLens
       # play the upload), audio with a waveform preview and video with no poster; and every preview has
       # its ThumbHash. Text, spreadsheets and other files have neither. The mock decodes nothing, so
       # sizes are unknown, audio has no peaks, and audio and video never get an adaptive stream.
-      def rendering(asset, processed) = { **rendered_file(asset, processed), 'hls' => nil, 'hlsStatus' => nil }
+      def rendering(asset, processed) = { **rendered_file(asset, processed), 'hls' => nil }
 
       # The rendered file and preview of {#rendering}.
       def rendered_file(asset, processed)
@@ -1728,8 +1782,8 @@ module CalmLens
       # Answers like the CDN (serveAssetResource.ts): `original` is the upload; `rendered` the image,
       # PDF, video or audio file `content.rendered` describes; `preview` the still `content.preview`
       # describes; `hls` the adaptive stream's files, which the mock never prepares; `embed` a small
-      # page standing in for the embed page of any asset; and `placeholder` the preview's ThumbHash as a PNG, public
-      # whatever the asset's visibility or moderation. A safety hold refuses every resource. Other resources pass delivery checks first,
+      # page standing in for the embed page of any asset; and `placeholder` the preview's ThumbHash as a PNG.
+      # A safety hold refuses every resource. Other resources pass delivery checks first,
       # which refuse everyone (content still uploading, blocked or purged, failed processing, removed
       # content), then an age-restricted asset needs `viewerClaims.ageConfirmed=true` whatever the key,
       # and a private asset needs an API key with `assets:download` for its folder. The mock converts
@@ -1746,20 +1800,32 @@ module CalmLens
         grant, item = resolve_asset(raw_segments[2])
         return grant if grant.is_a?(Response)
         return asset_not_found unless item && RESOURCES.include?(resource)
-        if resource == 'original' && grant && !grant[:original]
-          return error(ErrorCodes::SIGNED_URL_ORIGINAL_NOT_GRANTED, "This signed asset URL doesn't grant the original file", status: 403)
-        end
+
+        refused = refuse_viewer(item, resource, grant, headers)
+        return refused if refused
 
         params = URI.decode_www_form(query.to_s).to_h
         # A grant authorises a private asset without the API key.
         authorised = !grant.nil? || can_download?(item['folderId'], headers)
         return info(method, item, authorised, params) if resource == 'info'
         return not_available if item['content']['safetyHold']
-        return placeholder(method, item) if resource == 'placeholder'
+        return placeholder(method, item, authorised) if resource == 'placeholder'
 
         deliver(method, item, resource, params, selected ? options || {} : nil, authorised)
       end
 
+      # What a grant doesn't cover, or, like the CDN, a private asset for anyone without a grant or the
+      # project's API key: it answers as an unknown asset does, whatever its state, except for its
+      # info, which has its own rule. An error response, or nil.
+      def refuse_viewer(item, resource, grant, headers)
+        if resource == 'original' && grant && !grant[:original]
+          return error(ErrorCodes::SIGNED_URL_ORIGINAL_NOT_GRANTED, "This signed asset URL doesn't grant the original file", status: 403)
+        end
+        return if grant || item['visibility'] == 'public' || header(headers, 'X-Api-Key') == @api_key
+
+        asset_not_found unless resource == 'info'
+      end
+
       # Whether the path after the resource selects a lens or transform, and its options; nil when the
       # CDN refuses it. Like the CDN, the adaptive stream's files sit beneath `/hls/` (its master
       # playlist is `/hls/index.m3u8`). Otherwise the selector after the resource is read
@@ -1800,12 +1866,15 @@ module CalmLens
         restricted = item['visibility'] != 'public'
         return asset_not_found if restricted && !authorised
 
+        restricted ||= %w[blocked purged].include?(item['classification']['moderation']['status'])
+        return not_available if restricted && !authorised
+
         claims = JSON.parse(params.fetch('viewerClaims', '{}'))
         body = { 'id' => item['id'], 'projectId' => item['projectId'], 'type' => item['type'], 'externalUrl' => item['externalUrl'],
                  'content' => item['content'].slice(*%w[format width height durationSeconds pageCount rendered preview hls]),
                  'availability' => availability(item, claims.is_a?(Hash) && claims['ageConfirmed'] == true) }
         cdn_response(method, JSON.generate(body), { 'content-type' => 'application/json',
-                                                    'cache-control' => "#{restricted ? 'private' : 'public'}, max-age=60",
+                                                    'cache-control' => restricted ? 'private, no-store' : 'public, no-cache',
                                                     'cache-tag' => "asset-#{item['id']}" })
       rescue JSON::ParserError
         error(ErrorCodes::INVALID_VIEWER_CLAIMS, 'Invalid viewer claims', status: 400)
@@ -1914,15 +1983,18 @@ module CalmLens
 
       def not_available = error('asset/not-available', 'Asset is not available', status: 403)
 
-      # Like the CDN's placeholder handler: the preview's ThumbHash, public whatever the asset's
-      # visibility or moderation; refused for purged assets and assets without one (not yet
-      # processed, without a preview, or content removed).
-      def placeholder(method, item)
+      # A preview requires access for private or blocked assets and disappears with its content.
+      def placeholder(method, item, authorised)
+        private_asset = item['visibility'] != 'public'
+        blocked = item['classification']['moderation']['status'] == 'blocked'
+        return asset_not_found if private_asset && !authorised
+        return not_available if blocked && !authorised
+
         thumbhash = item.dig('content', 'preview', 'thumbhash')
         return not_available if thumbhash.nil? || item['classification']['moderation']['status'] == 'purged'
 
         cdn_response(method, Placeholder.png(thumbhash),
-                     'content-type' => 'image/png', 'cache-control' => 'public, max-age=3600',
+                     'content-type' => 'image/png', 'cache-control' => private_asset || blocked ? 'private, no-store' : 'public, no-cache',
                      'cache-tag' => "asset-#{item['id']}", 'etag' => "\"#{thumbhash}\"")
       end
 

data/lib/calmlens/testing/mock_decision.rb

@@ -5,11 +5,13 @@ require_relative 'classification'
 module CalmLens
   # A moderation decision for {MockServerClient}'s `moderate:` option or
   # {MockServerClient#complete_processing}, started with {.of}: flag the categories it found, with
-  # their scores and qualifiers, and mark the categories it couldn't assess. Each call checks its
-  # names and scores and raises `sdk/invalid-argument` for one CalmLens doesn't have.
+  # their scores and qualifiers, mark the categories it couldn't assess, and leave it waiting for
+  # human review. Each call checks its names and scores and raises `sdk/invalid-argument` for one
+  # CalmLens doesn't have.
   #
   # @example
   #   CalmLens::MockDecision.of('blocked').flag('violence', 0.9, 'violence-threat' => 0.9).not_evaluated('profanity')
+  #   CalmLens::MockDecision.of('limited').flag('violence', 0.5).pending_review('uncertain', ['violence'])
   class MockDecision
     # Where the mock's moderation leaves an upload: `pending` (still processing), `failed`
     # (processing failed, retryable), or a decision with that moderation status (`purged` also
@@ -19,6 +21,9 @@ module CalmLens
     STATUS_ACTIONS = { 'allowed' => 'allow', 'limited' => 'limit', 'age-restricted' => 'age-restrict', 'blocked' => 'block',
                        'purged' => 'purge' }.freeze
     private_constant :STATUS_ACTIONS
+    # Why a decision waits for human review.
+    PENDING_REVIEW_REASONS = %w[sampled uncertain].freeze
+    private_constant :PENDING_REVIEW_REASONS
 
     # @return [String]
     attr_reader :status
@@ -81,18 +86,40 @@ module CalmLens
       self
     end
 
+    # Leaves the decision waiting for human review, as `classification.moderation.pendingReview`
+    # reports: `sampled`, or `uncertain` with the `uncertain_categories` that made it so.
+    # {MockServerClient#decide} clears it; {Assets#decide} doesn't, as with the API.
+    # @param reason [String] `sampled` or `uncertain`
+    # @param uncertain_categories [Array<String>]
+    # @return [self]
+    # @raise [InvalidArgumentError] for a `pending` or `failed` decision, another reason, a `sampled`
+    #   reason with uncertain categories, or an unknown category
+    def pending_review(reason, uncertain_categories = [])
+      raise Internal.invalid("a #{@status} decision can't wait for review") if undecided?
+
+      reason = reason.to_s
+      raise Internal.invalid("reason must be one of #{PENDING_REVIEW_REASONS.join(', ')}") unless PENDING_REVIEW_REASONS.include?(reason)
+      raise Internal.invalid('uncertain_categories must be an Array') unless uncertain_categories.is_a?(Array)
+      raise Internal.invalid('a sampled review has no uncertain categories') if reason == 'sampled' && !uncertain_categories.empty?
+
+      @pending_review = { 'reason' => reason, 'uncertainCategories' => uncertain_categories.map { |category| known_category(category) } }
+      self
+    end
+
     # The report a decided asset gets, as the API sends it: every category (unflagged ones
     # evaluated with score 0), the policy's actions, the automated status and `flaggedCategories`.
+    # @param requested_at [Integer] when a pending review joined the queue, in epoch milliseconds
     # @return [Hash{String => Object}, nil] `categories`, `score` and `policy`; nil for `pending` and `failed`
-    def report
+    def report(requested_at = 0)
       return if undecided?
 
       evaluated = (MockClassification::CATEGORIES - @not_evaluated).map { |category| [category, @flags.dig(category, :score) || 0] }
       { 'raw' => { 'categories' => MockClassification::CATEGORIES.to_h { |category| [category, category_report(category)] },
                    'hashMatches' => [] },
-        'categories' => evaluated.to_h { |category, value| [category, { 'score' => value, 'action' => action(value) }] },
+        'categories' => evaluated.to_h { |category, value| [category, policy_result(value)] },
         # The mock keeps no policies, so no policy is named.
         'explanationComplete' => true, 'policy' => nil, 'source' => 'policy', 'rule' => nil, 'automatedStatus' => @status,
+        'pendingReview' => @pending_review && { 'requestedAt' => requested_at, **@pending_review },
         'regions' => [], 'linkSafety' => nil, 'flaggedCategories' => evaluated.reject { |_, value| action(value) == 'allow' }.map(&:first) }
     end
 
@@ -102,9 +129,15 @@ module CalmLens
 
     def undecided? = %w[pending failed].include?(@status)
 
-    def check_category(category)
+    def known_category(category)
       category = category.to_s
       raise Internal.invalid("#{category} is not a CalmLens category") unless MockClassification::CATEGORIES.include?(category)
+
+      category
+    end
+
+    def check_category(category)
+      category = known_category(category)
       raise Internal.invalid("a #{@status} decision has no findings") if undecided?
       raise Internal.invalid("#{category} is already in this decision") if @flags.key?(category) || @not_evaluated.include?(category)
 
@@ -115,6 +148,13 @@ module CalmLens
 
     def action(score) = @status != 'allowed' && score >= 0.5 ? STATUS_ACTIONS[@status] : 'allow'
 
+    # A category's policy result. The mock keeps no policies: the category's setting is the
+    # decision's own action.
+    def policy_result(score)
+      { 'score' => score, 'action' => action(score), 'source' => { 'kind' => score >= 0.5 ? 'default' : 'below-threshold' },
+        'settings' => { 'action' => STATUS_ACTIONS[@status], 'allowances' => [], 'restrictions' => [] } }
+    end
+
     # The API's likelihood for a score (ClassificationCategories.ts, scoreToLikelihood).
     def likelihood(score)
       if score >= 0.8 then 'very-likely'

data/lib/calmlens/testing/test_inputs.rb

@@ -56,7 +56,7 @@ module CalmLens
     person = { 'box' => [2500, 1500, 5000, 8500] }
     face = ->(age = nil) { { 'box' => [3500, 2000, 3000, 3500], **(age ? { 'age' => age } : {}) } }
     # Ready-made scenarios (deeply frozen): a clean input, a limited one, adult images and text,
-    # regional delivery, content restricted in Germany, mixed instances in one category, and test
+    # regional delivery, delivery blocked in Germany, mixed instances in one category, and test
     # images with one person and face, nobody, an adult's face, a minor's face and a group of three.
     PRESETS = deep_freeze.call(
       clean: { 'instances' => [] },
@@ -66,7 +66,7 @@ module CalmLens
       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'),
+      germany: { 'instances' => [], 'regionalActions' => [{ 'region' => 'DE', 'action' => 'block' }] },
       mixed: { 'instances' => [{ 'category' => 'harassment', 'qualifiers' => %w[harassment-abuse harassment-documentary] },
                                { 'category' => 'harassment', 'qualifiers' => ['harassment-threat'] }] },
       one_face: { 'instances' => [], 'detections' => { 'people' => [person], 'faces' => [face.call] } },
@@ -97,7 +97,8 @@ module CalmLens
       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 'hate.regional-symbol'
+                 { 'instances' => [{ 'category' => 'hate', 'qualifiers' => %w[hate-symbol hate-nazi-symbols-public-display] }] }
                when 'sexual.involving-minors' then { 'instances' => [{ 'category' => 'sexual', 'qualifiers' => ['sexual-minors'] }] }
                when 'violence.graphic'
                  { 'instances' => [{ 'category' => 'violence', 'qualifiers' => %w[violence-injury violence-graphic] }] }

data/lib/calmlens/testing.rb

@@ -27,8 +27,10 @@ module CalmLens
   # grant (the default key has no grants), or the URL is signed: {CDN#sign_asset_url} returns
   # `{cdn_base_url}/assets/{project_id}/sig_…`, a readable grant that only the mock's CDN accepts,
   # which serves `original` only when signed with `original: true`. {#fetch_cdn} loads such a URL
-  # without the API key, as a browser would. {#decide} applies a reviewer's decision, and
-  # {Assets#wait_for_decision} takes no real time: a pending asset times out at once.
+  # without the API key, as a browser would; without the key or a grant, a private asset answers
+  # as an unknown one does, `asset/not-found` (404) whatever its state, and only its placeholder is
+  # public. {#decide} applies a reviewer's decision, and {Assets#wait_for_decision} takes no real
+  # time: a pending asset times out at once.
   # Filters join comparisons with `;` (and), which binds tighter than `,` (or), and group them with
   # `( … )`; list cursors resume after the last item returned. {Assets#search} is the API's keyword
   # search: every query word (case-insensitive, up to 8) must appear in a searchable field, and
@@ -78,7 +80,7 @@ module CalmLens
     REQUEST_FAILURES = %w[transport-error timeout].freeze
     # The methods {#fail_next_request} can target, by resource. Iterators are their list calls.
     OPERATIONS = { assets: %i[search list retrieve list_children list_timeline update create classify upload_part move
-                              retry explain wait_for_decision remove_content delete batch],
+                              retry explain decide wait_for_decision remove_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 retrieve_assigned create update reset upgrade set_automatic_updates delete
@@ -200,8 +202,9 @@ module CalmLens
 
     # Applies a reviewer's decision to a stored asset, as the portal or API would: the moderation
     # status changes (`purged` also removes the content), the review joins `manualReviews` with
-    # `decidedBy` the mock API key (`{ 'type' => 'api-key', 'id' => nil }`) and `applied: true`, and an
-    # `asset.<decision>` event whose `actor` is a `user` joins the events feed.
+    # `decidedBy` the mock API key (`{ 'type' => 'api-key', 'id' => nil }`) and `applied: true`, an
+    # `asset.<decision>` event whose `actor` is a `user` joins the events feed, and a waiting
+    # `pendingReview` is settled ({Assets#decide} leaves it waiting, as with the API).
     # @param asset_id [String]
     # @param decision [String] `allowed`, `limited`, `age-restricted`, `blocked` or `purged`
     # @return [Hash] the asset
@@ -271,7 +274,8 @@ module CalmLens
     # Fetches a URL of the mock's CDN as a browser would, with a GET and without the API key: a signed
     # asset URL from {CDN#sign_asset_url} (with a resource appended), or a public one from
     # {CDN#get_asset_url}. The request is recorded like any other. Error statuses are returned, not
-    # raised.
+    # raised. A private asset without a grant answers `asset/not-found` (404) whatever its state,
+    # except for its public placeholder.
     # @param url [String]
     # @return [Response] with its body read
     def fetch_cdn(url)

data/lib/calmlens/transform_schema.rb

@@ -46,20 +46,6 @@ module CalmLens
           "blur": {
             "type": "number"
           },
-          "redact": {
-            "type": "object",
-            "properties": {
-              "text": {
-                "type": "boolean"
-              },
-              "personalInformation": {
-                "type": "boolean"
-              },
-              "faces": {
-                "type": "boolean"
-              }
-            }
-          },
           "border": {
             "type": "object",
             "properties": {

data/lib/calmlens/transport.rb

@@ -19,7 +19,10 @@ module CalmLens
     # @!attribute open_timeout [Numeric] seconds allowed to open a connection.
     # @!attribute timeout [Numeric] seconds allowed for each read or write; not a whole-transfer deadline.
     Request = Struct.new(:method, :url, :headers, :body, :open_timeout, :timeout, keyword_init: true) do
+      # Struct's own `to_s` and `pretty_print` would show the headers, which hold the API key.
       def inspect = "#<#{self.class.name} #{method} #{url}>"
+      def to_s = inspect
+      def pretty_print(printer) = printer.text(inspect)
     end
 
     # Exceptions that mean the connection failed before a complete response arrived.

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.22.0'
+  VERSION = '0.23.1'
 end

data/sig/calmlens.rbs

@@ -470,8 +470,11 @@ module CalmLens
     # Flags `category` with a score from 0 to 1 and optional qualifier scores.
     def flag: (String | Symbol category, Numeric score, ?Hash[String | Symbol, Numeric] qualifiers) -> self
     def not_evaluated: (String | Symbol category) -> self
+    # Leaves the decision waiting for human review: `sampled`, or `uncertain` with the categories that made it so.
+    def pending_review: ("sampled" | "uncertain" | :sampled | :uncertain reason, ?Array[String | Symbol] uncertain_categories) -> self
     # The `categories`, `score` and `policy` a decided asset gets; nil for `pending` and `failed`.
-    def report: () -> Hash[String, json_value]?
+    # `requested_at` is when a pending review joined the queue, in epoch milliseconds.
+    def report: (?Integer requested_at) -> Hash[String, json_value]?
   end
 
   # What MockServerClient's `moderate:` callback receives.

data/sig/qualifiers.rbs

@@ -57,6 +57,7 @@ module CalmLens
     ?"sexual-educational" => qualifier_result,
     ?"sexual-discussion" => qualifier_result,
     ?"sexual-fictional" => qualifier_result,
+    ?"sexual-artistic" => qualifier_result,
     ?"sexual-support-prevention" => qualifier_result,
     ?"violence-attack" => qualifier_result,
     ?"violence-threat" => qualifier_result,

data/sig/types.rbs

@@ -102,8 +102,11 @@ module CalmLens
   # Preview. The adaptive stream of audio or video: HLS with fragmented MP4 (CMAF) segments, served
   # at the CDN's `hls` resource (`hls/index.m3u8`) and played by its `embed` resource. Renditions list
   # video from the largest down, then audio.
-  type asset_hls = { "renditions" => Array[asset_hls_rendition] }
-  type asset_hls_status = { "status" => String, "reason" => String? }
+  type asset_hls = {
+    "status" => String,
+    "reason" => String?,
+    "renditions" => Array[asset_hls_rendition]
+  }
   type asset_rendered_kind = "image" | "pdf" | "video" | "audio"
   # The asset's one displayable file, as the CDN's `rendered` resource serves it: an image, a PDF, or
   # browser-safe video or audio. `peaks` is an audio waveform's normalised peaks.
@@ -262,7 +265,6 @@ module CalmLens
     # Preview. The adaptive stream once streaming has prepared one for audio or video; `nil` for
     # other assets, until then, once the content is removed and while the asset is held.
     "hls" => asset_hls?,
-    "hlsStatus" => asset_hls_status?,
     "preview" => asset_preview?
   }
 
@@ -434,8 +436,7 @@ module CalmLens
   }
   # Where OCR found text in an image, and whether it is personal information.
   type text_region = { "box" => bounding_box, "personalInformation" => bool }
-  # `status: "evaluated"` carries `textRegions`, where OCR found text (redaction transforms blur
-  # these regions); `"not-evaluated"` carries `reason`. The text itself is `content.extractedText`.
+  # `status: "evaluated"` carries `textRegions`, where OCR found text; `"not-evaluated"` carries `reason`. The text itself is `content.extractedText`.
   type ocr_result = {
     "status" => "evaluated" | "not-evaluated",
     ?"textRegions" => Array[text_region],
@@ -543,11 +544,6 @@ module CalmLens
     ?anim: bool,
     ?background: String,
     ?blur: number,
-    ?redact: {
-      ?text: bool,
-      ?personalInformation: bool,
-      ?faces: bool
-    },
     ?border: {
       ?color: String,
       ?width: number
@@ -590,11 +586,6 @@ module CalmLens
     ?"anim" => bool,
     ?"background" => String,
     ?"blur" => number,
-    ?"redact" => {
-      ?"text" => bool,
-      ?"personalInformation" => bool,
-      ?"faces" => bool
-    },
     ?"border" => {
       ?"color" => String,
       ?"width" => number
@@ -635,12 +626,12 @@ module CalmLens
   type transform_input = String | image_transform_options_input
 
   type lens_type = "image" | "video" | "audio" | "document" | "website"
-  # ENSURE_LENS_BODY_SCHEMA: a lens definition, which the CDN serves once it is saved.
+  # ENSURE_LENS_BODY_SCHEMA: a lens definition, which the CDN serves once it is saved unless `active` is false.
   type lens_definition = {
     identifier: String,
     name: String,
     type: lens_type,
-    active: bool,
+    ?active: bool,
     ?description: String?,
     ?transform: image_transform_options_input?
   }
@@ -1168,7 +1159,7 @@ module CalmLens
     identifier: String,
     name: String,
     type: lens_type,
-    active: bool,
+    ?active: bool,
     ?description: String?,
     ?transform: image_transform_options_input?,
     ?request_options: request_options

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.1
 platform: ruby
 authors:
 - CalmLens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-08 00:00:00.000000000 Z
+date: 2026-11-10 00:00:00.000000000 Z
 dependencies: []
 description: 'Server-side client for the CalmLens API: moderation, uploads, events,
   webhooks and CDN delivery.'