calmlens 0.20.0 → 0.22.0

data/lib/calmlens/upload_body.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module CalmLens
   # An upload payload: a binary String, or an IO streamed with an exact byte count (or, when its
   # length is unknown, until it ends, sent with chunked transfer encoding).
@@ -98,6 +100,20 @@ module CalmLens
       UploadBody.new(@source.slice(offset, length))
     end
 
+    # This body as the `file` part of an upload form, after an `options` part holding
+    # `options_json`: `multipart/form-data` with a random boundary. A stream stays a stream, read
+    # as the form is sent, and the form can be sent again whenever this body can.
+    # @return [Array(UploadBody, String)] the form and its Content-Type.
+    def to_form(options_json, type)
+      boundary = "calmlens-#{SecureRandom.uuid}"
+      head = "--#{boundary}\r\nContent-Disposition: form-data; name=\"options\"\r\nContent-Type: application/json\r\n\r\n".b +
+             options_json.b + "\r\n--#{boundary}\r\nContent-Disposition: form-data; name=\"file\"\r\n".b +
+             "Content-Type: #{type.delete("\r\n")}\r\n\r\n".b
+      tail = "\r\n--#{boundary}--\r\n".b
+      source = @source.is_a?(String) ? head + @source + tail : FormReader.new(head, @source, tail)
+      [UploadBody.new(source), "multipart/form-data; boundary=#{boundary}"]
+    end
+
     # The bytes, read fully. Used only by the offline mock.
     def read_all
       return @source if @source.is_a?(String)
@@ -111,9 +127,12 @@ module CalmLens
     class IOReader
       attr_reader :size
 
-      def initialize(io, size)
+      # @param bounded [Boolean] the stream goes on after `size` bytes (a slice of a larger file), so
+      #   reading stops there without checking for more.
+      def initialize(io, size, bounded: false)
         @io = io
         @size = size
+        @bounded = bounded
         @remaining = size
         @start = (io.pos if io.respond_to?(:pos) && io.respond_to?(:seek))
       rescue IOError, SystemCallError
@@ -125,7 +144,7 @@ module CalmLens
       # 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)
+        IOReader.new(@io, length, bounded: true)
       end
 
       def rewind
@@ -138,6 +157,8 @@ module CalmLens
         return read_unsized(length, buffer) if @size.nil?
 
         if @remaining.zero?
+          return length.nil? ? ''.b : buffer&.clear && nil if @bounded
+
           extra = @io.read(1)
           unless extra.nil? || extra.empty?
             raise Internal.invalid('The stream holds more bytes than sizeInBytes',
@@ -169,6 +190,68 @@ module CalmLens
         read(length, buffer) || raise(EOFError)
       end
     end
+
+    # An upload form around a streamed file: the form's head, the file's bytes as an {IOReader}
+    # reads them, then its closing boundary.
+    class FormReader
+      def initialize(head, file, tail)
+        @head = head
+        @file = file
+        @tail = tail
+        @size = file.size && (head.bytesize + file.size + tail.bytesize)
+        rewind_pieces
+      end
+
+      attr_reader :size
+
+      def rewindable? = @file.rewindable?
+
+      def rewind
+        @file.rewind
+        rewind_pieces
+      end
+
+      # Reads like IO#read: everything left without a length, else up to `length` bytes, nil at the end.
+      def read(length = nil, buffer = nil)
+        return (buffer ? buffer.replace(''.b) : ''.b) if length&.zero?
+
+        output = ''.b
+        until @pieces.empty? || (length && output.bytesize >= length)
+          chunk = read_piece(length && (length - output.bytesize))
+          chunk.nil? || chunk.empty? ? next_piece : output << chunk
+        end
+        return buffer&.clear && nil if output.empty? && length
+
+        buffer ? buffer.replace(output) : output
+      end
+
+      def readpartial(length, buffer = nil)
+        read(length, buffer) || raise(EOFError)
+      end
+
+      private
+
+      def rewind_pieces
+        @pieces = %i[head file tail]
+        @offset = 0
+      end
+
+      def next_piece
+        @pieces.shift
+        @offset = 0
+      end
+
+      # Up to `length` bytes (all, without one) of the current piece; empty or nil once it is used up.
+      def read_piece(length)
+        piece = @pieces.first
+        return @file.read(length) if piece == :file
+
+        text = piece == :head ? @head : @tail
+        chunk = text.byteslice(@offset, length || text.bytesize).to_s
+        @offset += chunk.bytesize
+        chunk
+      end
+    end
   end
   private_constant :UploadBody
 end

data/lib/calmlens/upload_mime_types.rb

@@ -3,7 +3,7 @@
 # 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.
+# and any other type is refused with upload/unsupported-type.
 
 module CalmLens
   module Internal
@@ -32,6 +32,14 @@ module CalmLens
       'application/msword',
       'application/rtf',
       'application/vnd.oasis.opendocument.text',
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      'application/vnd.ms-excel.sheet.macroenabled.12',
+      'application/vnd.ms-excel',
+      'application/vnd.oasis.opendocument.spreadsheet',
+      'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      'application/vnd.ms-powerpoint.presentation.macroenabled.12',
+      'application/vnd.ms-powerpoint',
+      'application/vnd.oasis.opendocument.presentation',
       'application/javascript',
       'application/json',
       'application/x-javascript',

data/lib/calmlens/upload_tokens.rb

@@ -26,7 +26,7 @@ module CalmLens
     # Signs a single-use token. Hand it to the browser as its bearer token; give each upload its own.
     # @option options [String] :upload_preset_id the preset the token may upload through
     # @option options [String] :external_id the external ID the uploaded asset gets (not empty)
-    # @option options [Integer] :expires_in_seconds lifetime, 1 to 3600 (default 600)
+    # @option options [Integer] :expires_in lifetime in seconds, 1 to 3600 (default 600)
     # @return [Hash] `{'token' => String, 'expiresAt' => Integer}` (milliseconds since the Unix epoch)
     def sign(options)
       call(options, __method__) { UploadTokens.sign_at(@api_key, options, now: (Time.now.to_f * 1000).to_i, nonce: SecureRandom.uuid) }
@@ -39,9 +39,9 @@ module CalmLens
       api, = Internal.options(options)
       preset_id = api['uploadPresetId']
       Internal.segment(preset_id)
-      ttl = api.fetch('expiresInSeconds', DEFAULT_TTL_SECONDS)
+      ttl = api.fetch('expiresIn', DEFAULT_TTL_SECONDS)
       unless ttl.is_a?(Integer) && ttl.between?(1, MAX_TTL_SECONDS)
-        raise Internal.invalid("expiresInSeconds must be a whole number from 1 to #{MAX_TTL_SECONDS}")
+        raise Internal.invalid("expiresIn must be a whole number from 1 to #{MAX_TTL_SECONDS}")
       end
 
       external_id = api['externalId']

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.20.0'
+  VERSION = '0.22.0'
 end

data/lib/calmlens/webhooks.rb

@@ -15,25 +15,34 @@ module CalmLens
   WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300
 
   # A verified webhook delivery. The body has the shape of an {Events#list} item:
-  # `{id, projectId, type, severity, title, description, assetId, asset, facts, createdAt}`.
+  # `{id, projectId, actor, type, severity, title, description, assetId, assetSequence, asset, facts, createdAt}`.
   # Fields CalmLens adds later are kept in {#payload}, as are unknown asset and fact fields.
   #
   # @!attribute id [String] the event ID.
   # @!attribute project_id [String]
+  # @!attribute actor [Hash, nil] who caused the event: `{'type', 'id'}`, with `type` `user`, `api-key`,
+  #   `automated` or `system`, and `id` the user's or API key's ID, or nil when it was not recorded.
   # @!attribute type [String] such as `asset.allowed`. New types may appear: ignore unknown ones.
   # @!attribute severity [String, nil] `low` or `high`.
   # @!attribute title [String, nil]
   # @!attribute description [String, nil]
   # @!attribute asset_id [String, nil]
+  # @!attribute asset_sequence [Integer, nil] increases with each event about the same asset; nil for
+  #   events not about an asset. Deliveries can arrive out of order: see {#newer_than?}.
   # @!attribute asset [Hash, nil] the asset's status when the event was created.
   # @!attribute facts [Array<Hash>] `{'key', 'value', 'url'?}` entries registered for the event type.
   # @!attribute created_at [Integer] milliseconds since the epoch.
   # @!attribute payload [Hash{String => Object}] the delivery body as received, with every field.
-  WebhookEvent = Struct.new(:id, :project_id, :type, :severity, :title, :description, :asset_id, :asset, :facts,
-                            :created_at, :payload, keyword_init: true) do
+  WebhookEvent = Struct.new(:id, :project_id, :actor, :type, :severity, :title, :description, :asset_id, :asset_sequence, :asset,
+                            :facts, :created_at, :payload, keyword_init: true) do
     # @return [Boolean] true for a test send from the portal or CLI.
     def test? = Webhooks.test_event?(self)
 
+    # @param last_sequence [Integer, nil] the highest `assetSequence` applied for this event's asset
+    # @return [Boolean] whether to apply this event after it.
+    # @see Webhooks.newer_asset_event?
+    def newer_than?(last_sequence) = Webhooks.newer_asset_event?(self, last_sequence)
+
     # @return [Hash{String => Object}] the delivery body as received, with every field.
     def to_payload = payload
   end
@@ -79,16 +88,34 @@ module CalmLens
       facts.is_a?(Array) && facts.any? { |fact| fact.is_a?(Hash) && fact['key'] == 'test' && fact['value'] == true }
     end
 
+    # Whether to apply `event` after `last_sequence`, the highest `assetSequence` you have applied
+    # for its asset (nil when none). Deliveries can arrive out of order: an event about an asset is
+    # newer only with a higher `assetSequence`, so a retried or repeated delivery of an earlier one
+    # returns false. Events that aren't about an asset have no sequence and are always new. Store
+    # the highest `assetSequence` applied per `assetId` and ignore lower ones.
+    # @param event [WebhookEvent, Hash] a parsed delivery, or a delivery body with string keys
+    # @param last_sequence [Integer, nil]
+    # @return [Boolean]
+    def newer_asset_event?(event, last_sequence)
+      sequence = event.is_a?(Hash) ? event['assetSequence'] : event.asset_sequence
+      sequence.nil? || last_sequence.nil? || sequence > last_sequence
+    end
+
     # Converts an event from {Events#list} to the JSON body of its webhook delivery, which has the
-    # same fields: `description`, `assetId` and `asset` are nil when absent.
+    # same fields: `description`, `assetId`, `assetSequence` and `asset` are nil when absent, and
+    # `actor` is left out when the event has none.
     # @param event [Hash] an event with string keys, as {Events#list} returns it
-    # @return [Hash] `{ 'id', 'projectId', 'type', 'severity', 'title', 'description', 'assetId', 'asset', 'facts', 'createdAt' }`
+    # @return [Hash] `{ 'id', 'projectId', 'actor', 'type', 'severity', 'title', 'description', 'assetId',
+    #   'assetSequence', 'asset', 'facts', 'createdAt' }`
     def to_payload(event)
       raise Internal.invalid('event must be a Hash') unless event.is_a?(Hash)
 
-      { 'id' => event['id'], 'projectId' => event['projectId'], 'type' => event['type'], 'severity' => event['severity'],
-        'title' => event['title'], 'description' => event['description'], 'assetId' => event['assetId'],
-        'asset' => event['asset'], 'facts' => event['facts'], 'createdAt' => event['createdAt'] }
+      payload = { 'id' => event['id'], 'projectId' => event['projectId'] }
+      payload['actor'] = event['actor'] if event.key?('actor')
+      payload.merge('type' => event['type'], 'severity' => event['severity'], 'title' => event['title'],
+                    'description' => event['description'], 'assetId' => event['assetId'],
+                    'assetSequence' => event['assetSequence'], 'asset' => event['asset'], 'facts' => event['facts'],
+                    'createdAt' => event['createdAt'])
     end
 
     # Checks a delivery's signature and freshness in constant time. Pass the `signature` and
@@ -149,9 +176,10 @@ module CalmLens
       body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
       raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not a CalmLens event') unless event?(body)
 
-      WebhookEvent.new(id: body['id'], project_id: body['projectId'], type: body['type'], severity: body['severity'],
+      WebhookEvent.new(id: body['id'], project_id: body['projectId'], actor: body['actor'], type: body['type'], severity: body['severity'],
                        title: body['title'], description: body['description'], asset_id: body['assetId'],
-                       asset: body['asset'], facts: body.fetch('facts', []), created_at: body['createdAt'], payload: body)
+                       asset_sequence: body['assetSequence'], asset: body['asset'], facts: body.fetch('facts', []),
+                       created_at: body['createdAt'], payload: body)
     rescue JSON::ParserError, EncodingError => e
       raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not JSON'), cause: e
     end
@@ -163,9 +191,17 @@ module CalmLens
                           body['projectId'].is_a?(String) && body['createdAt'].is_a?(Numeric)
 
       optional = ->(key, *types) { !body.key?(key) || types.any? { |type| type.nil? ? body[key].nil? : body[key].is_a?(type) } }
-      asset = body['asset']
       optional.call('severity', String) && optional.call('title', String) && optional.call('description', String, nil) &&
-        optional.call('assetId', String, nil) && (asset.nil? || (asset.is_a?(Hash) && asset['id'].is_a?(String))) &&
+        optional.call('assetId', String, nil) && optional.call('assetSequence', Numeric, nil) && nested?(body)
+    end
+
+    # The nested fields, when present: `actor` is `{type, id}` with a String type and a String or null
+    # ID, `asset` has a String `id` and `facts` lists `{key, value, url?}` entries.
+    def nested?(body)
+      actor = body.fetch('actor', { 'type' => '' })
+      asset = body['asset']
+      actor.is_a?(Hash) && actor['type'].is_a?(String) && (actor['id'].nil? || actor['id'].is_a?(String)) &&
+        (asset.nil? || (asset.is_a?(Hash) && asset['id'].is_a?(String))) &&
         (!body.key?('facts') || (body['facts'].is_a?(Array) && body['facts'].all? { |fact| fact?(fact) }))
     end
 
@@ -191,7 +227,7 @@ module CalmLens
       raise Internal.invalid("Webhook payload must be the raw body String, not a #{payload.class}. " \
                              'Read request.raw_post (Rails) or request.body.read (Rack, Sinatra) before parsing.')
     end
-    private_class_method :decode_event, :event?, :fact?, :header, :raw_body
+    private_class_method :decode_event, :event?, :nested?, :fact?, :header, :raw_body
   end
 
   # @see Webhooks.signature_header
@@ -214,4 +250,13 @@ module CalmLens
 
   # @see Webhooks.test_event?
   def self.test_webhook_event?(...) = Webhooks.test_event?(...)
+
+  # @see Webhooks.newer_asset_event?
+  def self.newer_asset_event?(...) = Webhooks.newer_asset_event?(...)
+
+  # @see EventFacts.value
+  def self.get_event_fact(...) = EventFacts.value(...)
+
+  # @see EventFacts.values
+  def self.get_event_facts(...) = EventFacts.values(...)
 end

data/lib/calmlens.rb

@@ -29,5 +29,6 @@ require_relative 'calmlens/upload_tokens'
 require_relative 'calmlens/events'
 require_relative 'calmlens/cdn'
 require_relative 'calmlens/lenses'
+require_relative 'calmlens/project_configuration'
 require_relative 'calmlens/server_client'
 require_relative 'calmlens/webhooks'

data/sig/calmlens.rbs

@@ -31,6 +31,7 @@ module CalmLens
                      ?headers: Hash[String, String], ?request_id: String?) -> void
     # Whole seconds from the `Retry-After` header.
     def retry_after: () -> Integer?
+    def local?: () -> bool
     def not_found?: () -> bool
     def retryable?: () -> bool
     def self.build: (String code, ?String? message, ?status: Integer?, ?details: Hash[String, json_value]?,
@@ -121,6 +122,10 @@ module CalmLens
     attr_reader upload_tokens: UploadTokens
     attr_reader events: Events
     attr_reader cdn: CDN
+    attr_reader lenses: Lenses
+    attr_reader upload_presets: UploadPresets
+    attr_reader project_settings: ProjectSettings
+    attr_reader metadata_fields: MetadataFields
     attr_reader project_id: String
     attr_reader base_url: String
     attr_reader cdn_base_url: String
@@ -148,16 +153,12 @@ module CalmLens
   end
 
   class Assets < Resource
-    # The moderation status before a decision.
-    PENDING_MODERATION_STATUS: String
-    # Processing statuses after which no decision arrives without a retry.
-    FINISHED_PROCESSING_STATUSES: Array[String]
+    # The classification statuses of a settled asset; wait_for_decision returns at the first.
+    SETTLED_STATUSES: Array[String]
     DECISION_POLL_FIRST_DELAY: Float
     DECISION_POLL_FACTOR: Float
     DECISION_POLL_MAX_DELAY: Float
     DEFAULT_DECISION_TIMEOUT: Integer
-    DEFAULT_SIGNED_URL_SECONDS: Integer
-    MAX_SIGNED_URL_SECONDS: Integer
     BATCH_OPERATIONS: Array[asset_batch_operation]
     MAX_BATCH_ASSETS: Integer
 
@@ -168,24 +169,30 @@ module CalmLens
     def list_children: (list_asset_children_options options) -> asset_page
     def each_child: (list_asset_children_options options) { (asset) -> void } -> nil
                   | (list_asset_children_options options) -> Enumerator[asset, nil]
+    def list_timeline: (list_asset_timeline_options options) -> asset_timeline_page
+    def each_timeline_segment: (list_asset_timeline_options options) { (media_segment) -> void } -> nil
+                             | (list_asset_timeline_options options) -> Enumerator[media_segment, nil]
     def retrieve: (asset_id_options options) -> asset
     def wait_for_decision: (wait_for_decision_options options) -> asset
     def update: (update_asset_options options) -> asset
     def retry: (asset_id_options options) -> asset
     def decide: (decide_asset_options options) -> asset
     def explain: (explain_asset_options options) -> asset
-    def delete_content: (asset_id_options options) -> asset
+    def remove_content: (asset_id_options options) -> asset
     def delete: (asset_id_options options) -> nil
     def batch: (batch_assets_options options) -> batch_assets_response
     def move: (move_asset_options options) -> asset
-    def create_signed_url: (create_signed_url_options options) -> signed_url
     def create: (upload_options options) -> asset
     def classify: (upload_options options) -> asset
     def upload_part: (upload_part_options options) -> asset
+    # Waits between decision checks; a mock client's waits take no real time.
+    private def sleep: (Numeric seconds) -> void
   end
 
   class Folders < Resource
     def list: (?list_folders_options options) -> folder_page
+    def each: (?list_folders_options options) { (folder) -> void } -> nil
+            | (?list_folders_options options) -> Enumerator[folder, nil]
     def create: (create_folder_options options) -> folder
     def retrieve: (folder_id_options options) -> folder
     def update: (update_folder_options options) -> folder
@@ -195,26 +202,64 @@ module CalmLens
 
   class HashLists < Resource
     def list: (?list_hash_lists_options options) -> hash_list_page
+    def each: (?list_hash_lists_options options) { (hash_list) -> void } -> nil
+            | (?list_hash_lists_options options) -> Enumerator[hash_list, nil]
     def retrieve: (hash_list_id_options options) -> hash_list
     def create: (create_hash_list_options options) -> hash_list
     def update: (update_hash_list_options options) -> hash_list
     def delete: (hash_list_id_options options) -> nil
     def list_entries: (list_hash_list_entries_options options) -> hash_list_entry_page
+    def each_entry: (list_hash_list_entries_options options) { (hash_list_entry) -> void } -> nil
+                  | (list_hash_list_entries_options options) -> Enumerator[hash_list_entry, nil]
     def add_entry: (add_hash_list_entry_options options) -> hash_list_entry
     def remove_entry: (hash_list_entry_id_options options) -> nil
   end
 
   class Policies < Resource
-    def list: (?list_policies_options options) -> policy_list
+    def list: (?list_policies_options options) -> policy_page
+    def each: (?list_policies_options options) { (policy) -> void } -> nil
+            | (?list_policies_options options) -> Enumerator[policy, nil]
     def retrieve: (policy_id_options options) -> policy
+    # The policy the project moderates with.
+    def retrieve_assigned: (?request_only_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 reset: (restore_policy_options options) -> policy
+    def upgrade: (restore_policy_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 Lenses < Resource
+    def list: (?list_lenses_options options) -> lens_page
+    def each: (?list_lenses_options options) { (lens) -> void } -> nil
+            | (?list_lenses_options options) -> Enumerator[lens, nil]
+    def create: (create_lens_options options) -> lens
+    def retrieve: (lens_id_options options) -> lens
+    def update: (update_lens_options options) -> lens
+    def delete: (lens_id_options options) -> nil
+  end
+
+  class UploadPresets < Resource
+    def list: (?list_upload_presets_options options) -> upload_preset_page
+    def each: (?list_upload_presets_options options) { (upload_preset) -> void } -> nil
+            | (?list_upload_presets_options options) -> Enumerator[upload_preset, nil]
+    def ensure: (ensure_upload_presets_options options) -> ensure_upload_presets_response
+    def delete: (upload_preset_id_options options) -> nil
+  end
+
+  class ProjectSettings < Resource
+    def get: (?request_only_options options) -> project_settings_resource
+    def update: (update_project_settings_options options) -> project_settings_resource
+  end
+
+  class MetadataFields < Resource
+    def list: (?request_only_options options) -> metadata_fields_resource
+    def ensure: (ensure_metadata_fields_options options) -> metadata_fields_resource
+    def delete: (delete_metadata_field_options options) -> nil
+  end
+
   class UploadTokens < Resource
     TOKEN_PREFIX: String
     SIGNING_CONTEXT: String
@@ -238,7 +283,19 @@ module CalmLens
   end
 
   class CDN < Resource
+    # Every CDN resource beneath an asset URL.
+    RESOURCES: Array[cdn_resource]
+    # A signed asset URL's lifetime in seconds when `expires_in` is omitted.
+    DEFAULT_SIGNED_URL_EXPIRES_IN: Integer
+    # The longest signed asset URL lifetime, in seconds.
+    MAX_SIGNED_URL_EXPIRES_IN: Integer
+    # The start of the asset segment that names an asset by its external ID.
+    EXTERNAL_ID_PREFIX: String
+    # The ISO 3166-1 alpha-2 countries a viewer's `region` can be.
+    VIEWER_COUNTRIES: Array[String]
     def get_asset_url: (asset_url_options options) -> String
+    def sign_asset_url: (sign_asset_url_options options) -> signed_asset_url
+    def get_asset_info: (String url, ?viewer_claims: viewer_claims?) -> asset_info
     def serve: (serve_options options) -> Response
              | [T] (serve_options options) { (Response) -> T } -> T
   end
@@ -247,12 +304,16 @@ module CalmLens
   class WebhookEvent < Struct[untyped]
     attr_accessor id: String
     attr_accessor project_id: String
+    # nil for a delivery without one.
+    attr_accessor actor: actor?
     # New types may appear: ignore unknown ones.
     attr_accessor type: event_type | String
     attr_accessor severity: event_severity?
     attr_accessor title: String?
     attr_accessor description: String?
     attr_accessor asset_id: String?
+    # Increases with each event about the same asset; nil for events not about an asset.
+    attr_accessor asset_sequence: Integer?
     attr_accessor asset: event_asset?
     attr_accessor facts: Array[event_fact]
     # Milliseconds since the Unix epoch.
@@ -260,9 +321,10 @@ module CalmLens
     # The delivery body as received, with every field.
     attr_accessor payload: Hash[String, json_value]
     def initialize: (?id: String, ?project_id: String, ?type: event_type | String, ?severity: event_severity?, ?title: String?,
-                     ?description: String?, ?asset_id: String?, ?asset: event_asset?, ?facts: Array[event_fact],
+                     ?description: String?, ?asset_id: String?, ?asset_sequence: Integer?, ?asset: event_asset?, ?facts: Array[event_fact],
                      ?created_at: Integer, ?payload: Hash[String, json_value]) -> void
     def test?: () -> bool
+    def newer_than?: (Integer? last_sequence) -> bool
     # The delivery body as received, with every field.
     def to_payload: () -> Hash[String, json_value]
   end
@@ -286,6 +348,16 @@ module CalmLens
     def self.parse_event: (payload: String, secret: String, ?signature: String?, ?timestamp: String?, ?headers: webhook_headers?,
                            ?tolerance_seconds: Integer, ?now: number) -> WebhookEvent
     def self.test_event?: (WebhookEvent | Hash[String, untyped] event) -> bool
+    def self.newer_asset_event?: (WebhookEvent | Hash[String, untyped] event, Integer? last_sequence) -> bool
+  # The value of an event's fact by key (the first, when the event repeats it), or nil without one.
+  def self.get_event_fact: (WebhookEvent | Hash[String, untyped] event, String key) -> event_fact_value
+  # An event's facts as values by key; a repeated key keeps its first value.
+  def self.get_event_facts: (WebhookEvent | Hash[String, untyped] event) -> Hash[String, event_fact_value]
+  end
+
+  module EventFacts
+    def self.value: (WebhookEvent | Hash[String, untyped] event, String key) -> event_fact_value
+    def self.values: (WebhookEvent | Hash[String, untyped] event) -> Hash[String, event_fact_value]
   end
 
   def self.create_webhook_signature_header: (payload: String, timestamp: String | Integer, secret: String) -> String
@@ -298,6 +370,11 @@ module CalmLens
   def self.parse_webhook_event: (payload: String, secret: String, ?signature: String?, ?timestamp: String?,
                                  ?headers: webhook_headers?, ?tolerance_seconds: Integer, ?now: number) -> WebhookEvent
   def self.test_webhook_event?: (WebhookEvent | Hash[String, untyped] event) -> bool
+  def self.newer_asset_event?: (WebhookEvent | Hash[String, untyped] event, Integer? last_sequence) -> bool
+  # The value of an event's fact by key (the first, when the event repeats it), or nil without one.
+  def self.get_event_fact: (WebhookEvent | Hash[String, untyped] event, String key) -> event_fact_value
+  # An event's facts as values by key; a repeated key keeps its first value.
+  def self.get_event_facts: (WebhookEvent | Hash[String, untyped] event) -> Hash[String, event_fact_value]
 
   # require 'calmlens/testing'
   module Testing
@@ -325,6 +402,8 @@ module CalmLens
       # The HTTP status the mock answered with; nil when the request failed without a response.
       attr_accessor status: Integer?
       def json: () -> json_value
+      # An upload form's `options` (parsed) and `file` (its bytes); nil for any other body.
+      def form: () -> { 'options' => Hash[String, json_value], 'file' => String }?
     end
 
     interface _Clock
@@ -366,6 +445,8 @@ module CalmLens
     def enqueue: (body: json_input, ?status: Integer, ?headers: Hash[String, String]) -> self
     def enqueue_raw: (body: String, ?status: Integer, ?headers: Hash[String, String]) -> self
     def enqueue_error: (Exception error) -> self
+    # Fetches a mock CDN URL with a GET and without the API key, as a browser would.
+    def fetch_cdn: (String url) -> Response
     def enqueue_event: (mock_event_input event) -> event
     # Applies a reviewer's decision and adds the matching `asset.<decision>` event.
     def decide: (String asset_id, asset_moderation_decision decision) -> asset
@@ -416,6 +497,12 @@ module CalmLens
     QUALIFIERS: Hash[String, Array[String]]
     # Qualifiers the input type sets, which a TestInputs scenario cannot list.
     INPUT_QUALIFIERS: Array[String]
+    # Test scenario detections: entries per list, the basis points of a full side, the oldest age
+    # and the age presets.
+    TEST_DETECTIONS_MAX: Integer
+    TEST_DETECTION_BOX_MAX: Integer
+    TEST_FACE_AGE_MAX: Integer
+    TEST_FACE_AGE_PRESETS: Array[String]
   end
 
   # Signed test inputs: text codes, test images and media phrases signed with a project's secret
@@ -426,9 +513,20 @@ module CalmLens
     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] }
+    # `[left, top, width, height]`: Integers in basis points of the image, 0 to 10000, inside it.
+    type detection_box = [Integer, Integer, Integer, Integer]
+    # A person a test image reports, with an optional Integer confidence from 0 to 100.
+    type test_person = { "box" => detection_box, ?"confidence" => Integer }
+    # A face's age: a preset, or a range of Integers from 0 to 120 with `low` at most `high`.
+    type test_face_age = "adult" | "minor" | { "low" => Integer, "high" => Integer }
+    # A face a test image reports, with an optional confidence and age.
+    type test_face = { "box" => detection_box, ?"confidence" => Integer, ?"age" => test_face_age }
+    # The people and faces a test image reports: at most 32 of each, or `unavailable` to report the
+    # feature as not evaluated.
+    type test_detections = { ?"people" => Array[test_person] | "unavailable", ?"faces" => Array[test_face] | "unavailable" }
     # 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] }
+                      "instances" => Array[test_instance], ?"detections" => test_detections }
     type signal = classification_category | "sexual.involving-minors" | "harassment.insult" | "sexual.adult"
                 | "hate.regional-symbol" | "violence.graphic"
     type media_signal = classification_category | "violence.graphic"
@@ -447,7 +545,8 @@ module CalmLens
     REGIONS: Array[region]
     SIGNALS: Array[signal]
     MEDIA_SIGNALS: Array[media_signal]
-    # clean, limited, adult_image, adult_text, regional_delivery, germany and mixed (deeply frozen).
+    # clean, limited, adult_image, adult_text, regional_delivery, germany, mixed, one_face, no_face,
+    # adult_face, minor_face and group (deeply frozen).
     PRESETS: Hash[Symbol, scenario]
 
     def self.for_signal: (signal signal, ?("text" | "image") kind) -> scenario