calmlens 0.20.0 → 0.22.0

data/lib/calmlens/project_configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # The project's upload presets: the rules for uploads made from browsers and apps. {#ensure}
+  # creates or replaces presets by `key`, for applications that declare theirs in code or
+  # configuration. Reach it through {ServerClient#upload_presets}.
+  class UploadPresets < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'uploadPresets'
+
+    # Lists one page of the project's upload presets, oldest first unless `sort` says otherwise.
+    # @option options [String] :cursor the previous page's `nextCursor`
+    # @option options [Integer] :page_size 1 to 100, default 50
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`; `createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
+    def list(options = {})
+      call(options, __method__) do |api, request|
+        cursor_page(request('GET', project('upload-presets'), query: api, request_options: request), 'upload preset')
+      end
+    end
+
+    # Iterates every upload preset of the project, fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam upload_preset [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_item(options, __method__, method(:list), &block)
+    end
+
+    # Creates each preset, or replaces it with the definition sent, by `key`. Fields left out take
+    # their defaults; an unchanged preset keeps its revision. Every preset is checked before any is
+    # saved. Send each preset's `revision` (0 for one that must not exist yet) to refuse a change
+    # made since with `upload-preset/revision-conflict`.
+    # @option options [Array<Hash>] :upload_presets `[{key:, name:, revision:, access:, enabled:, ...}]`,
+    #   at most 50
+    # @return [Hash] `uploadPresets`: the stored presets, in the order sent.
+    def ensure(options)
+      call(options, __method__) do |api, request|
+        request('PUT', project('upload-presets'), body: api, request_options: request)
+      end
+    end
+
+    # Deletes an upload preset. Browsers can no longer upload through it; assets already uploaded stay.
+    # @option options [String] :upload_preset_id
+    # @return [nil]
+    def delete(options)
+      call(options, __method__) do |api, request|
+        request('DELETE', "/upload-presets/#{Internal.segment(api['uploadPresetId'])}", request_options: request)
+        nil
+      end
+    end
+  end
+
+  # The project's settings, with defaults filled in. {#update} replaces them: settings left out
+  # return to their defaults. Send the `revision` you read to refuse a change made since with
+  # `project-settings/revision-conflict`. Reach it through {ServerClient#project_settings}.
+  class ProjectSettings < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'projectSettings'
+
+    # @return [Hash] `projectId`, `revision` and `settings`.
+    def get(options = {})
+      call(options, __method__) { |_api, request| request('GET', project('settings'), request_options: request) }
+    end
+
+    # Replaces the project's settings; unchanged settings keep their revision. The project's policy
+    # and metadata fields have their own methods.
+    # @option options [Integer] :revision the revision you read
+    # @option options [Hash] :settings the complete settings
+    # @option options [Numeric] :search_indexing_budget_units needed when turning on
+    #   `aiMediaSearchEnabled`: the most indexing units you accept for existing media
+    # @return [Hash] `projectId`, `revision` and `settings`.
+    def update(options)
+      call(options, __method__) { |api, request| request('PUT', project('settings'), body: api, request_options: request) }
+    end
+  end
+
+  # The project's metadata fields, in display order. They share the project settings' `revision`;
+  # {#ensure} creates or replaces fields by ID and keeps the others. Reach it through
+  # {ServerClient#metadata_fields}.
+  class MetadataFields < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'metadataFields'
+
+    # @return [Hash] `projectId`, `revision` and `fields`.
+    def list(options = {})
+      call(options, __method__) { |_api, request| request('GET', project('metadata-fields'), request_options: request) }
+    end
+
+    # Creates each field, or replaces it by ID. Other fields are kept; new ones are added at the end.
+    # @option options [Integer] :revision the revision you read
+    # @option options [Array<Hash>] :fields `[{id:, title:, type:, icon:, color:, description:}]`
+    # @return [Hash] `projectId`, `revision` and `fields`.
+    def ensure(options)
+      call(options, __method__) { |api, request| request('PUT', project('metadata-fields'), body: api, request_options: request) }
+    end
+
+    # Deletes a field definition; assets keep the metadata values they hold.
+    # @option options [String] :field_id
+    # @option options [Integer] :revision the revision you read
+    # @return [nil]
+    def delete(options)
+      call(options, __method__) do |api, request|
+        request('DELETE', project("metadata-fields/#{Internal.segment(api['fieldId'])}"),
+                query: without(api, 'fieldId'), request_options: request)
+        nil
+      end
+    end
+  end
+end

data/lib/calmlens/resource.rb

@@ -19,9 +19,9 @@ module CalmLens
     # beside a request's; Internal::OPTION_KEYS, generated from the API, has the rest.
     LOCAL_OPTION_KEYS = {
       'assets.waitForDecision' => %w[assetId timeout].freeze,
-      'cdn.getAssetUrl' => %w[assetIdentifier lens resource transform viewerClaims].freeze,
-      'cdn.serve' => %w[assetIdentifier init lens resource transform viewerClaims].freeze,
-      'uploadTokens.sign' => %w[expiresInSeconds externalId uploadPresetId].freeze
+      'cdn.getAssetUrl' => %w[assetId externalId lens projectId resource transform viewerClaims].freeze,
+      'cdn.serve' => %w[assetId externalId init lens projectId resource transform viewerClaims].freeze,
+      'uploadTokens.sign' => %w[expiresIn externalId uploadPresetId].freeze
     }.freeze
     private_constant :LOCAL_OPTION_KEYS
 
@@ -30,9 +30,10 @@ module CalmLens
     # `sdk/invalid-argument` instead of being silently dropped.
     # An option given as nil is left out, as if omitted, unless the API takes null for it
     # (Internal::NULLABLE_OPTION_KEYS), such as `description: nil` to clear a description;
-    # `keep_nil: true` sends every option as given, as for a lens definition.
-    def call(options, method, keep_nil: false)
-      operation = [self.class::OPERATIONS, Internal.camelize(method)].compact.join('.')
+    # `keep_nil: true` sends every option as given, as for a lens definition. `prefix` names the
+    # operation's resource, the resource's own unless the method belongs to the client itself.
+    def call(options, method, keep_nil: false, prefix: self.class::OPERATIONS)
+      operation = [prefix, Internal.camelize(method)].compact.join('.')
       check_option_keys(options, operation)
       api, request = Internal.options(options)
       nullable = Internal::NULLABLE_OPTION_KEYS.fetch(operation, [])
@@ -84,6 +85,23 @@ module CalmLens
       end
     end
 
+    # A list's response, once it is a cursor page: a Hash with an `items` Array. `what` names the
+    # items in the `sdk/invalid-response` error otherwise.
+    def cursor_page(response, what)
+      return response if response.is_a?(Hash) && response['items'].is_a?(Array)
+
+      raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, "Invalid #{what} page")
+    end
+
+    # Iterates the items of every page `list` returns for `options`, from its `cursor`, yielding each
+    # to `block`. `method` names the public iterator, whose options are checked like the list's.
+    def each_item(options, method, list, &block)
+      api, request = call(options, method) { |*split| split }
+      listing = pages(api['cursor']) { |cursor| list.call(api.merge('cursor' => cursor, 'request_options' => request)) }
+      listing.each { |page| page['items'].each(&block) }
+      nil
+    end
+
     # Records a cursor an iteration sends, raising `sdk/invalid-response` (with `details['cursor']`)
     # when a page with more to follow hands back one it already sent, which would repeat pages forever.
     def new_cursor!(sent, cursor)

data/lib/calmlens/server_client.rb

@@ -49,6 +49,14 @@ module CalmLens
     attr_reader :events
     # @return [CDN]
     attr_reader :cdn
+    # @return [Lenses]
+    attr_reader :lenses
+    # @return [UploadPresets]
+    attr_reader :upload_presets
+    # @return [ProjectSettings]
+    attr_reader :project_settings
+    # @return [MetadataFields]
+    attr_reader :metadata_fields
 
     # @param api_key [String] a project API key. Keep it on your server.
     # @param project_id [String]
@@ -64,7 +72,7 @@ module CalmLens
     # @param max_response_bytes [Integer] the largest response body read; a larger one fails with
     #   `sdk/response-too-large`, before it is read when its `Content-Length` says so.
     # @param max_retries [Integer] retries of requests that are safe to repeat: GET/HEAD, and uploads,
-    #   which carry an `Idempotency-Key`. Connection failures, timeouts, 429, 502, 503, 504 and
+    #   which carry an `Idempotency-Key`. Connection failures, timeouts, 429, 500, 502, 503, 504 and
     #   `idempotency/request-in-progress` are retried with jittered exponential backoff, honouring
     #   `Retry-After`. Other writes are never retried. 0 disables retries.
     # @param retry_base_delay [Numeric] seconds before the first retry when the API gives no
@@ -98,6 +106,9 @@ module CalmLens
       @events = Events.new(@session)
       @cdn = CDN.new(@session)
       @lenses = Lenses.new(@session)
+      @upload_presets = UploadPresets.new(@session)
+      @project_settings = ProjectSettings.new(@session)
+      @metadata_fields = MetadataFields.new(@session)
     end
 
     # @return [String]
@@ -119,11 +130,11 @@ module CalmLens
       nil
     end
 
-    # Creates or updates named lenses (saved transforms) and returns them. Definitions
-    # this client already saved are not sent again. Supplying the same definition and version is
-    # idempotent; changing a lens needs a higher `version`. More than 100 new definitions are sent in
-    # consecutive requests, in order.
-    # @option options [Array<Hash>] :lenses `[{identifier:, name:, type:, version:, transform:, ...}]`
+    # Creates named lenses (saved transforms), or changes them to these definitions, and returns
+    # 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:, ...}]`
     # @return [Array<Hash>] the saved lenses, in the given order.
     def ensure_lenses(options) = @lenses.ensure_lenses(options)
 

data/lib/calmlens/session.rb

@@ -10,7 +10,7 @@ module CalmLens
   # The resources share one session per client. It never prints the API key.
   # @api private
   class Session
-    RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
     USER_AGENT = "calmlens-ruby/#{VERSION} (ruby/#{RUBY_VERSION})".freeze
 
     # Raised through the transport so an exception from the caller's streaming block is
@@ -99,10 +99,11 @@ module CalmLens
 
     # Sends a CDN request, retrying like an API read, and returns the last response rather than
     # raising an error status. With a block, yields the streaming {Response} and returns the block's
-    # value; otherwise returns the response with its body read.
-    def cdn(method, url, headers, request_options, &block)
+    # value; otherwise returns the response with its body read. `authenticate: false` sends no API
+    # key, as a browser would.
+    def cdn(method, url, headers, request_options, authenticate: true, &block)
       limit = request_options.fetch(:max_response_bytes, nil)
-      execute(method, url, headers, nil, request_options, allow_http_errors: true) do |response|
+      execute(method, url, headers, nil, request_options, allow_http_errors: true, authenticate: authenticate) do |response|
         next response.tap { response.body(limit: limit) } unless block
 
         streaming = Response.new(status: response.status, headers: response.headers) do |&sink|
@@ -122,6 +123,14 @@ module CalmLens
       end
     end
 
+    # Fetches JSON from the CDN without the API key, as a browser would, and returns it parsed. An
+    # error status raises the error the CDN's body names, such as `signed-url/expired`.
+    def cdn_json(url)
+      execute('GET', url, { 'Accept' => 'application/json' }, nil, {}, authenticate: false) do |response|
+        parse('GET', response, @max_response_bytes)
+      end
+    end
+
     # Resolves lens definitions, sending only definitions this client has not saved before, at most
     # ServerClient::ENSURE_LENSES_MAX_PER_REQUEST per request, in order. Calls are serialized, so concurrent calls
     # for the same definitions send them once.
@@ -142,7 +151,7 @@ module CalmLens
             raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Unexpected lens response')
           end
 
-          # A new version of a lens replaces the cached definition with the same identifier.
+          # A changed lens replaces the cached definition with the same identifier.
           chunk.keys.zip(returned).each do |key, lens|
             @lenses.delete_if { |_, saved| saved['identifier'] == lens['identifier'] }
             @lenses[key] = lens
@@ -156,9 +165,16 @@ module CalmLens
       end
     end
 
-    def headers_for(extra)
-      extra.reject { |name, _| %w[x-api-key user-agent authorization].include?(name.downcase) }
-           .merge('X-Api-Key' => @api_key, 'User-Agent' => USER_AGENT)
+    # Drops the cached definitions of the lenses the block selects, which lenses.create, update
+    # and delete changed, so ensure_lenses sends their definitions again.
+    def forget_lenses(&selected)
+      @lens_lock.synchronize { @lenses.delete_if { |_, lens| selected.call(lens) } }
+    end
+
+    def headers_for(extra, authenticate: true)
+      headers = extra.reject { |name, _| %w[x-api-key user-agent authorization].include?(name.downcase) }
+                     .merge('User-Agent' => USER_AGENT)
+      authenticate ? headers.merge('X-Api-Key' => @api_key) : headers
     end
 
     private
@@ -168,7 +184,7 @@ module CalmLens
     def lens_key(lens)
       fields = { 'identifier' => lens['identifier'], 'name' => lens['name'], 'description' => lens['description'],
                  'type' => lens['type'], 'transform' => lens['transform'] }
-      %w[active version].each { |name| fields[name] = lens[name] if lens.key?(name) }
+      fields['active'] = lens['active'] if lens.key?('active')
       JSON.generate(canonical(fields))
     end
 
@@ -186,14 +202,15 @@ module CalmLens
         returned.zip(sent).all? { |saved, definition| saved.is_a?(Hash) && saved['identifier'] == definition['identifier'] }
     end
 
-    # Sends a request, retrying transport failures, timeouts, 429, 502–504 and
+    # Sends a request, retrying transport failures, timeouts, 429, 500, 502–504 and
     # `idempotency/request-in-progress` when it is safe to repeat: reads, and requests with an
     # `Idempotency-Key` whose body can be sent again. Redirects are never followed.
-    def execute(method, url, headers, body, request_options, allow_http_errors: false, deadline: nil, &handler)
+    def execute(method, url, headers, body, request_options, allow_http_errors: false, deadline: nil, authenticate: true, &handler)
       retries = request_options.fetch(:max_retries, @max_retries)
       retryable = retries.positive? && (%w[GET HEAD].include?(method) || headers.key?('Idempotency-Key')) &&
                   (body.nil? || body.replayable?)
-      request = Transport::Request.new(method: method, url: url, headers: headers_for(headers), body: body&.content,
+      request = Transport::Request.new(method: method, url: url, headers: headers_for(headers, authenticate: authenticate),
+                                       body: body&.content,
                                        open_timeout: request_options.fetch(:open_timeout, @open_timeout),
                                        timeout: request_options.fetch(:timeout, @timeout))
       limit = request_options.fetch(:max_response_bytes, @max_response_bytes)

data/lib/calmlens/testing/asset_filters.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/mockAssetFilters.ts from ASSET_FILTER_FIELDS (packages/shared-backend/src/AssetFilters.ts) and listFilterOperators (PaginationUtils.ts); do not edit.
+# A filter may name only these fields, each with only its operators; anything else is
+# filter/invalid. A number field's value must be a finite number, and `null` is a
+# missing value only on a nullable field.
+module CalmLens
+  module MockAssetFilters
+    # Each field a filter may name, with its kind, whether it is nullable and its operators.
+    FIELDS = {
+      'id' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'parentId' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'folderId' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'uploadPresetId' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'createdAt' => { kind: 'number', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'updatedAt' => { kind: 'number', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'type' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'name' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'description' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'externalId' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'externalUrl' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'authorId' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'tags' => { kind: 'list', nullable: false, operators: ['=in=', '=out='].freeze }.freeze,
+      'visibility' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'upload.status' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'upload.updatedAt' => { kind: 'number', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'classification.status' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'classification.updatedAt' => { kind: 'number', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'classification.completedAt' => { kind: 'number', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'classification.moderation.status' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.status' => { kind: 'text', nullable: false, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.removalReason' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.updatedAt' => { kind: 'number', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.format' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.extension' => { kind: 'text', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+      'content.sizeInBytes' => { kind: 'number', nullable: true, operators: ['==', '!=', '>', '>=', '<', '<=', '=in=', '=out='].freeze }.freeze,
+    }.freeze
+  end
+end

data/lib/calmlens/testing/classification.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Generated by packages/sdk-contract/mockClassification.ts from packages/shared/src/ModerationCategories.ts and ModerationPolicyDimensions.ts; do not edit.
+# Generated by packages/sdk-contract/mockClassification.ts from packages/shared/src/ModerationCategories.ts, ModerationPolicyDimensions.ts and TestTriggers.ts; do not edit.
 module CalmLens
   module MockClassification
     # The parent categories, in the API's order.
@@ -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-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-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,
@@ -20,5 +20,11 @@ module CalmLens
 
     # Qualifiers the input type sets, which a test input scenario cannot list.
     INPUT_QUALIFIERS = ["sexual-text", "violence-text"].freeze
+
+    # Test scenario detections: entries per list, the basis points of a full side, the oldest age and the age presets.
+    TEST_DETECTIONS_MAX = 32
+    TEST_DETECTION_BOX_MAX = 10000
+    TEST_FACE_AGE_MAX = 120
+    TEST_FACE_AGE_PRESETS = ["adult", "minor"].freeze
   end
 end