calmlens 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f31d8d0e9739bebd69a0bab938d60914fb7173c8543b5521bcd5ac97e441311a
-  data.tar.gz: c85ad7397dd68637309b17204ff12dc7d52ec1e6415d66c42bacb7a000b9e9cf
+  metadata.gz: 977f88cea877f294fefbc6259eef7e99c7327ba3e90333540da37c86ad74b599
+  data.tar.gz: 1ac90ad7c9fa1a7c11bf1abce6595efffb58b0cbdbd2a93035f1f1bc8f0c5ab9
 SHA512:
-  metadata.gz: 7fb2274df7c0dfa834c97e786ab3b37816ec447c5d7694a293866a75882f11e4a052e684c3c1559a477a7e7419a02144a2af232291bf21f868bffa9fada5eed8
-  data.tar.gz: '090730bd39a5d48f41a7d7cfdbda56538166304f1af6cf6b22c9046997135f15a66384054a9e02751d168696b46c5a811b01abf825fc77f8a1f04b808da1c8d1'
+  metadata.gz: 6654f2b874569fd13005016adc0a7efbec542db6bf378fa04d5ebfe4f3bb43c7cd85b04c504ac6110966d826f9a92c1e1d9a82aa796e19ed01b3f00920cc1179
+  data.tar.gz: 26e933bc44b4577d13be2e01907c9578cd84ebe3ec3dd2e51d969da5b6f990254466a3728dccb0ecd6e1a2c74699769ed5d5bfd0f8ab90a36ce8224bcf171e9b

data/lib/calmlens/assets.rb

@@ -359,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

@@ -54,8 +54,8 @@ module CalmLens
     #   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.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
+    #   iframe), `placeholder` (a small blurred PNG, without age confirmation; private or blocked assets
+    #   require a signed URL or download permission) 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
     #   apply to `preview`, and to `rendered` when it is an image; the CDN refuses them on rendered PDFs,
     #   video and audio with `transform/invalid`, and the SDK refuses them on the other resources and

data/lib/calmlens/internal.rb

@@ -14,7 +14,7 @@ module CalmLens
     IDEMPOTENCY_KEY = /\A[^\r\n\0]+\z/
     HEADER_VALUE = /\A[^\r\n\0]*\z/
     # The CDN resources that take no lens or transform: the exact upload, the adaptive stream, the embed page,
-    # the public placeholder and the display info.
+    # the placeholder and the display info.
     UNSELECTABLE_CDN_RESOURCES = %w[original hls embed placeholder info].freeze
 
     module_function

data/lib/calmlens/testing/fake_api.rb

@@ -730,7 +730,8 @@ module CalmLens
       end
 
       def show_project_settings
-        settings = { 'optOutJurisdictions' => [], 'blockUnmoderatedAssets' => true, 'storeSensitiveMetadata' => false,
+        settings = { 'retainContent' => true, 'optOutJurisdictions' => [], 'blockUnmoderatedAssets' => true,
+                     'storeSensitiveMetadata' => false,
                      'streamingEnabled' => false, 'aiMediaSearchEnabled' => false, 'remoteUrlRule' => nil,
                      'websiteSubmissionsPerMinute' => nil }.merge(@project_settings)
         settings['humanReview'] = { 'allowedSamplePercent' => 0, 'restrictedSamplePercent' => 0, 'uncertaintyMarginPercent' => 0,
@@ -842,8 +843,9 @@ module CalmLens
         end
         now = @now.call
         mime = options['contentType'].to_s
-        processing = options['processingOptions'] || { 'keepContentAfterProcessing' => false }
-        keep = processing.is_a?(Hash) && processing['keepContentAfterProcessing'] == true
+        processing = (options['processingOptions'] || {}).dup
+        processing['retainContent'] = show_project_settings['settings']['retainContent'] if processing['retainContent'].nil?
+        keep = processing.is_a?(Hash) && processing['retainContent'] == true
         context = options['context'].is_a?(Hash) ? ModerationContext.select_items(options['context'].fetch('items', [])) : []
         # Fields the API returns as null when they are not set.
         asset = { 'id' => @create_id.call('asset'), 'projectId' => @project_id, 'parentId' => nil, 'parentPages' => [],
@@ -946,8 +948,12 @@ module CalmLens
         fail!(ErrorCodes::UPLOAD_PRESET_DISABLED) unless preset['enabled']
         check_preset_fields(preset, fields)
         check_preset_limits(preset, fields, data)
+        retain = fields.dig('processingOptions', 'retainContent')
+        retain = preset.dig('processingOptions', 'retainContent') if retain.nil?
         fields.merge('folderId' => preset['folderId'] || fields['folderId'], 'visibility' => preset['visibility'],
-                     'processingOptions' => fields['processingOptions'] || deep_copy(preset['processingOptions']))
+                     'processingOptions' => (fields['processingOptions'] || deep_copy(preset['processingOptions']) || {}).merge(
+                       'retainContent' => retain
+                     ))
       end
 
       def check_preset_fields(preset, fields)
@@ -1782,8 +1788,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
@@ -1809,21 +1815,21 @@ module CalmLens
         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
-      # public placeholder and its info, which has its own rule. An error response, or nil.
+      # 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 %w[placeholder info].include?(resource)
+        asset_not_found unless resource == 'info'
       end
 
       # Whether the path after the resource selects a lens or transform, and its options; nil when the
@@ -1866,12 +1872,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)
@@ -1980,15 +1989,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.rb

@@ -17,7 +17,7 @@ module CalmLens
   # callback decides each upload, retry and rerun with a status or a {MockDecision}, and the events
   # feed gets the pipeline's `asset.uploaded`, `asset.classified`, `asset.<status>` and `asset.failed`
   # events. Without it, queued uploads stay `pending` until {#complete_processing} and the rest are
-  # `allowed`. Content is kept only with `keepContentAfterProcessing: true`; otherwise it is removed
+  # `allowed`. Content retention follows upload, preset and project settings; when disabled, content is removed
   # once classification is `completed`, as in the API.
   # A `purged` outcome removes the content with reason `policy`. The CDN answers like the real one:
   # `asset/not-available` (403) for blocked, purged, failed or removed content,
@@ -28,8 +28,8 @@ module CalmLens
   # `{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; 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
+  # as an unknown one does, `asset/not-found` (404) whatever its state, including its placeholder
+  # and display info. {#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
@@ -275,7 +275,7 @@ module CalmLens
     # 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. A private asset without a grant answers `asset/not-found` (404) whatever its state,
-    # except for its public placeholder.
+    # including its placeholder and display info.
     # @param url [String]
     # @return [Response] with its body read
     def fetch_cdn(url)

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.23.0'
+  VERSION = '0.24.0'
 end

data/sig/types.rbs

@@ -70,12 +70,12 @@ module CalmLens
     ?face_detection: { enabled: bool, ?age_estimation: bool }?,
     ?link_detection: { enabled: bool }?,
     # Preview. Prepares an adaptive stream (HLS) of audio or video, served at the `hls` resource and
-    # played by the `embed` resource; needs `keep_content_after_processing`. Left out, the project's
+    # played by the `embed` resource; needs `retain_content`. Left out, the project's
     # streaming setting decides.
     ?streaming: { enabled: bool }?
   }
   type processing_options_input = {
-    ?keep_content_after_processing: bool?,
+    ?retain_content: bool?,
     # Overrides the project's `storeSensitiveMetadata` setting: false removes embedded EXIF, XMP and
     # IPTC metadata before the image is stored; true stores it as uploaded.
     ?store_sensitive_metadata: bool?,
@@ -658,7 +658,7 @@ module CalmLens
   type upload_preset_access = "token" | "anyone"
   # An upload preset's processing options, as the API returns them.
   type upload_preset_processing_options = {
-    ?"keepContentAfterProcessing" => bool?,
+    ?"retainContent" => bool?,
     ?"storeSensitiveMetadata" => bool?,
     ?"features" => {
       ?"ocr" => { "enabled" => bool }?,
@@ -703,6 +703,7 @@ module CalmLens
   }
   type public_project_settings = {
     "optOutJurisdictions" => Array[String],
+    "retainContent" => bool,
     "blockUnmoderatedAssets" => bool,
     "storeSensitiveMetadata" => bool,
     "streamingEnabled" => bool,
@@ -1204,6 +1205,7 @@ module CalmLens
   # The complete settings: those left out return to their defaults.
   type project_settings_input = {
     ?opt_out_jurisdictions: Array[String],
+    ?retain_content: bool,
     ?block_unmoderated_assets: bool,
     ?store_sensitive_metadata: bool,
     ?streaming_enabled: bool,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - CalmLens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-09 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies: []
 description: 'Server-side client for the CalmLens API: moderation, uploads, events,
   webhooks and CDN delivery.'
@@ -69,7 +69,7 @@ metadata:
   homepage_uri: https://calmlens.com
   documentation_uri: https://calmlens.com/docs/sdk/ruby
   source_code_uri: https://github.com/CalmLens/sdks/tree/main/ruby
-  changelog_uri: https://calmlens.com/docs/changelog
+  changelog_uri: https://github.com/CalmLens/sdks/blob/main/ruby/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []