calmlens 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b99a6fc15b38b4dd664a1df33e33eb8943cbd57483e16d7b7224f93cbc23d2a1
-  data.tar.gz: 668bf0e79e7fad1838be8d4e3c0bc536a379ea0de4cf3943a97057ed5025a72a
+  metadata.gz: f31d8d0e9739bebd69a0bab938d60914fb7173c8543b5521bcd5ac97e441311a
+  data.tar.gz: c85ad7397dd68637309b17204ff12dc7d52ec1e6415d66c42bacb7a000b9e9cf
 SHA512:
-  metadata.gz: 00023a2b77c5dd78ebd7f0563ab9d152bede63882abc80c7a3e47d667f8e2d3ec54bade2c18fa4bd901167da1e8e3b7be2181491d1b3d5d1700bca568403d6ba
-  data.tar.gz: 7e8a4bcab13c13c6278169e15a54bec41a9fc5849c366dbff1ef0208b6fceeeece777c157c52ea2286bfcca2135c64e41c8b878c6456e534fce51fd368dd61fe
+  metadata.gz: 7fb2274df7c0dfa834c97e786ab3b37816ec447c5d7694a293866a75882f11e4a052e684c3c1559a477a7e7419a02144a2af232291bf21f868bffa9fada5eed8
+  data.tar.gz: '090730bd39a5d48f41a7d7cfdbda56538166304f1af6cf6b22c9046997135f15a66384054a9e02751d168696b46c5a811b01abf825fc77f8a1f04b808da1c8d1'

data/README.md

@@ -69,6 +69,7 @@ New statuses and fields may appear in later API versions. The SDK returns them u
 - [Serve content from the CDN](https://calmlens.com/docs/sdk/ruby#cdn-methods), with [lenses, transforms and signed URLs](https://calmlens.com/docs/sdk/ruby/reference#cdn-urls) and [age-restricted delivery](https://calmlens.com/docs/guides/delivering-assets#age-restricted-assets).
 - [Organise assets in folders](https://calmlens.com/docs/sdk/ruby/reference#folders), [search them](https://calmlens.com/docs/guides/search) and [page through lists](https://calmlens.com/docs/sdk/ruby#pagination).
 - [Match images against hash lists](https://calmlens.com/docs/sdk/ruby/reference#hash-lists).
+- Keep [upload presets](https://calmlens.com/docs/guides/upload-presets), project settings and metadata fields in your code: `upload_presets` (`list`, `each`, `ensure`, `delete`), `project_settings` (`get`, `update`) and `metadata_fields` (`list`, `ensure`, `delete`). `ensure` and `update` create or replace by key or ID, and the `revision` you read refuses a change made since.
 - [Read the events feed](https://calmlens.com/docs/sdk/ruby#pagination) and [verify webhooks in Rails or Rack](https://calmlens.com/docs/sdk/ruby#webhooks).
 - [Handle errors](https://calmlens.com/docs/sdk/ruby/reference#errors) with automatic [retries, timeouts and idempotency keys](https://calmlens.com/docs/sdk/ruby/reference#retries-and-timeouts).
 - [Type-check your code with RBS signatures](https://calmlens.com/docs/sdk/ruby/reference#types).
@@ -79,7 +80,7 @@ Every method is listed in the [Ruby SDK documentation](https://calmlens.com/docs
 
 `CalmLens::MockServerClient` from `calmlens/testing` runs the real client against an in-memory stand-in for the API and CDN, so you can test your integration offline. See [Ruby testing](https://calmlens.com/docs/sdk/ruby/testing).
 
-`CalmLens::TestInputs` signs test inputs with your project's test input key from the portal: `generate_text_code` turns a scenario, preset or signal into a text code, `paint_image` paints it as a test image, and `generate_media_code` gives a phrase for audio and video, so the real API returns the scenario you declared in projects with "Recognise test inputs" turned on. Submit a text code as the whole text and a test image as the whole upload.
+`CalmLens::TestInputs` signs test inputs with your project's test input key from the portal: `generate_text_code` turns a scenario, preset or signal into a text code, `paint_image` paints it as a test image, and `generate_media_code` gives a phrase for audio and video, so the real API returns the scenario you declared. Submit a text code as the whole text and a test image as the whole upload.
 
 ## Links
 

data/lib/calmlens/assets.rb

@@ -15,8 +15,11 @@ module CalmLens
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
     OPERATIONS = 'assets'
 
-    SUBMIT_QUERY_KEYS = %w[name description processingOptions visibility metadata tags authorId context externalId
-                           externalUrl folderId uploadPresetId].freeze
+    # The asset fields an upload carries in its body: the JSON body for text, the `options` part of
+    # an upload form for files. They never go in the URL, which proxies and servers log, and the
+    # API refuses them there.
+    UPLOAD_OPTION_KEYS = %w[name description processingOptions visibility metadata tags authorId context externalId
+                            externalUrl folderId uploadPresetId].freeze
     MAX_MULTIPART_IMAGE_BYTES = 20 * 1024 * 1024
     # The API's limits for one-request uploads: images up to 10 MiB (larger ones are uploaded in
     # parts), audio and video up to 50 MiB and other files up to 5,000 MiB.
@@ -276,6 +279,11 @@ module CalmLens
     # `{type:, data:}` where `data` is a binary String or an IO. An IO streams without being read into
     # memory; pass `size_in_bytes:` when its length is unknown (a pipe or socket).
     #
+    # Text is sent as a JSON body. Other content is sent as `multipart/form-data`: the asset's fields
+    # (name, description, metadata, author ID, context and so on) in its `options` part, then the
+    # file. The URL carries only transport values (`wait`, the content type and sizes), never the
+    # asset's fields.
+    #
     # The request carries an `Idempotency-Key` (generated unless you pass
     # `request_options: {idempotency_key:}`), so a retried upload never creates a second asset.
     #
@@ -302,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.
@@ -395,13 +404,37 @@ module CalmLens
       return upload_in_parts(options, request_options, wait, mime, body) if !multipart && splits?(content, body)
 
       check_upload_size(mime, body.size) unless multipart || @session.defer_upload_checks
-      query = options.slice(*SUBMIT_QUERY_KEYS).merge('wait' => wait, 'contentType' => content['type'],
-                                                      'sizeInBytes' => body.size)
-      query.merge!(first_part_query(options, content, mime, body)) if multipart
+      part_query = first_part_query(options, content, mime, body) if multipart
+      if content.key?('plainText')
+        return expect_asset(request('POST', project('assets'), query: { 'wait' => wait },
+                                                               body: text_body(options, content, multipart),
+                                                               idempotent: true, request_options: request_options))
+      end
+
+      query = { 'wait' => wait, 'contentType' => content['type'], 'sizeInBytes' => body.size }
+      send_form(query.merge(part_query || {}), upload_fields(options), content['type'], body, multipart, request_options)
+    end
+
+    # The asset fields an upload sends, without unset values.
+    def upload_fields(options) = options.slice(*UPLOAD_OPTION_KEYS).compact
+
+    # The JSON body of a text upload: its fields and `content`, or a first `part` with the sizes.
+    def text_body(options, content, multipart)
+      text = content.except('sizeInBytes')
+      return upload_fields(options).merge('content' => text) unless multipart
+
+      sizes = { 'sizeInBytes' => options['sizeInBytes'] || content['sizeInBytes'],
+                'totalSizeInBytes' => options['totalSizeInBytes'] }.compact
+      upload_fields(options).merge('part' => text, **sizes)
+    end
+
+    # Sends file content, or a first part, as an upload form: the fields in its `options` part and
+    # the bytes in its `file` part. The query holds only transport values.
+    def send_form(query, fields, type, body, multipart, request_options)
+      form, form_type = body.to_form(JSON.generate(fields), type)
       expect_asset(request('POST', project('assets'),
-                           query: query, raw: body, idempotent: true, request_options: request_options,
-                           upload: !content.key?('plainText'),
-                           headers: { 'Content-Type' => content['type'], 'X-CalmLens-Upload' => multipart ? 'part' : 'content' }))
+                           query: query, raw: form, idempotent: true, request_options: request_options, upload: true,
+                           headers: { 'Content-Type' => form_type, 'X-CalmLens-Upload' => multipart ? 'part' : 'content' }))
     end
 
     # Whether content goes in parts: not text, of known size, readable again and larger than a part.
@@ -428,12 +461,9 @@ module CalmLens
       piece = ->(number) { body.slice((number - 1) * part_size, [part_size, total - ((number - 1) * part_size)].min) }
       first = piece.call(1)
       type = options.dig('content', 'type')
-      query = options.slice(*SUBMIT_QUERY_KEYS).merge('wait' => wait, 'contentType' => type, 'sizeInBytes' => first.size,
-                                                      'partNumber' => 1, 'isFinal' => false, 'totalSizeInBytes' => total)
-      asset = expect_asset(request('POST', project('assets'),
-                                   query: query, raw: first, idempotent: true, upload: true,
-                                   request_options: request_options.merge(idempotency_key: key),
-                                   headers: { 'Content-Type' => type, 'X-CalmLens-Upload' => 'part' }))
+      query = { 'wait' => wait, 'contentType' => type, 'sizeInBytes' => first.size, 'partNumber' => 1, 'isFinal' => false,
+                'totalSizeInBytes' => total }
+      asset = send_form(query, upload_fields(options), type, first, true, request_options.merge(idempotency_key: key))
       send_remaining_parts(asset, count, piece, key, request_options)
     end
 
@@ -473,7 +503,7 @@ module CalmLens
                                                                                  headers: headers))
     end
 
-    # Keeps only the earlier posts CalmLens uses, which keeps a raw upload's query short.
+    # Keeps only the earlier posts CalmLens uses, which keeps an upload's body short.
     def with_used_context(options)
       return options unless options.key?('context')
 
@@ -483,7 +513,8 @@ module CalmLens
       options.merge('context' => { 'items' => ModerationContext.select_items(context['items']) })
     end
 
-    # The query of a first multipart part: its number, whether it is the last and the declared total.
+    # The transport values of a first multipart part: its number, whether it is the last and the
+    # declared total.
     def first_part_query(options, content, mime, body)
       total = options['totalSizeInBytes']
       unless total.nil? || (total.is_a?(Integer) && total.positive?)

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/error_codes.rb

@@ -40,12 +40,14 @@ module CalmLens
     PERMISSION_DENIED = 'auth/permission-denied'
     UPLOAD_TOO_LARGE = 'upload/too-large'
     DOCUMENT_TOO_MANY_ITEMS = 'document/too-many-items'
+    MEDIA_DURATION_LIMIT = 'media/duration-limit'
     INVALID_IMAGE = 'image/invalid'
     IMAGE_TOO_LARGE = 'image/too-large'
     FREE_UPLOADS_EXHAUSTED = 'usage/free-uploads-exhausted'
     UPLOADS_PAUSED = 'usage/uploads-paused'
     UNSUPPORTED_UPLOAD_TYPE = 'upload/unsupported-type'
     INVALID_UPLOAD_PAYLOAD = 'upload-payload/invalid'
+    UPLOAD_OPTIONS_IN_QUERY = 'upload/options-in-query'
     USE_UPLOAD_PART = 'upload/use-upload-part'
     UPLOAD_NOT_OPEN = 'upload/not-open'
     INVALID_UPLOAD_PART_NUMBER = 'upload-part/invalid-number'
@@ -102,6 +104,14 @@ module CalmLens
     UPLOAD_PRESET_DAILY_LIMIT_REACHED = 'upload-preset/daily-limit-reached'
     UPLOAD_PRESET_ORIGIN_NOT_ALLOWED = 'upload-preset/origin-not-allowed'
     UPLOAD_PRESET_FIELD_NOT_ALLOWED = 'upload-preset/field-not-allowed'
+    UPLOAD_PRESET_REVISION_CONFLICT = 'upload-preset/revision-conflict'
+    UPLOAD_PRESET_KEY_TAKEN = 'upload-preset/key-taken'
+    UPLOAD_PRESET_DAILY_LIMIT_REQUIRED = 'upload-preset/daily-limit-required'
+    UPLOAD_PRESET_INVALID_FOLDER = 'upload-preset/invalid-folder'
+    UPLOAD_PRESET_INVALID_POLICY = 'upload-preset/invalid-policy'
+    PROJECT_SETTINGS_REVISION_CONFLICT = 'project-settings/revision-conflict'
+    SEARCH_ESTIMATE_CHANGED = 'search/estimate-changed'
+    METADATA_FIELD_NOT_FOUND = 'metadata-field/not-found'
     UPLOAD_TOKEN_INVALID = 'upload-token/invalid'
     UPLOAD_TOKEN_EXPIRED = 'upload-token/expired'
     UPLOAD_TOKEN_USED = 'upload-token/used'
@@ -153,12 +163,14 @@ module CalmLens
       'auth/permission-denied' => 403,
       'upload/too-large' => 413,
       'document/too-many-items' => 422,
+      'media/duration-limit' => 422,
       'image/invalid' => 422,
       'image/too-large' => 422,
       'usage/free-uploads-exhausted' => 403,
       'usage/uploads-paused' => 402,
       'upload/unsupported-type' => 415,
       'upload-payload/invalid' => 400,
+      'upload/options-in-query' => 400,
       'upload/use-upload-part' => 409,
       'upload/not-open' => 409,
       'upload-part/invalid-number' => 409,
@@ -215,6 +227,14 @@ module CalmLens
       'upload-preset/daily-limit-reached' => 429,
       'upload-preset/origin-not-allowed' => 403,
       'upload-preset/field-not-allowed' => 400,
+      'upload-preset/revision-conflict' => 409,
+      'upload-preset/key-taken' => 409,
+      'upload-preset/daily-limit-required' => 400,
+      'upload-preset/invalid-folder' => 400,
+      'upload-preset/invalid-policy' => 400,
+      'project-settings/revision-conflict' => 409,
+      'search/estimate-changed' => 409,
+      'metadata-field/not-found' => 404,
       'upload-token/invalid' => 401,
       'upload-token/expired' => 401,
       'upload-token/used' => 409,

data/lib/calmlens/errors.rb

@@ -61,6 +61,15 @@ module CalmLens
       Error.parse_retry_after(headers['retry-after'])
     end
 
+    # @return [Boolean] true when the SDK raised this error itself, with no HTTP response: before
+    #   sending (an invalid argument or option, or content it checks first, such as
+    #   `upload/unsupported-type`), or because no response arrived (a timeout or a connection
+    #   failure). The code is the one the API would use; `status` and `request_id` are nil, so
+    #   branch on `code`.
+    def local?
+      status.nil?
+    end
+
     # @return [Boolean] true when the resource does not exist.
     def not_found?
       status == 404 || code.end_with?('/not-found')

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/option_keys.rb

@@ -62,6 +62,9 @@ module CalmLens
       'lenses.list' => %w[cursor pageSize sort].freeze,
       'lenses.retrieve' => %w[lensId].freeze,
       'lenses.update' => %w[active description lensId name transform type].freeze,
+      'metadataFields.delete' => %w[fieldId revision].freeze,
+      'metadataFields.ensure' => %w[fields revision].freeze,
+      'metadataFields.list' => %w[].freeze,
       'policies.assign' => %w[policyId].freeze,
       'policies.create' => %w[description name presetId settings].freeze,
       'policies.delete' => %w[policyId].freeze,
@@ -73,10 +76,16 @@ module CalmLens
       'policies.setAutomaticUpdates' => %w[enabled policyId presetVersion revision].freeze,
       'policies.update' => %w[description name policyId revision settings].freeze,
       'policies.upgrade' => %w[policyId presetVersion revision].freeze,
+      'projectSettings.get' => %w[].freeze,
+      'projectSettings.update' => %w[revision searchIndexingBudgetUnits settings].freeze,
       'text.classify' => %w[
         authorId context description externalId externalUrl folderId metadata name processingOptions tags text
         uploadPresetId visibility
-      ].freeze
+      ].freeze,
+      'uploadPresets.delete' => %w[uploadPresetId].freeze,
+      'uploadPresets.each' => %w[cursor pageSize sort].freeze,
+      'uploadPresets.ensure' => %w[uploadPresets].freeze,
+      'uploadPresets.list' => %w[cursor pageSize sort].freeze
     }.freeze
 
     # The option keys each method sends as null when given nil; any other option given as nil

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/server_client.rb

@@ -51,6 +51,12 @@ module CalmLens
     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]
@@ -100,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]
@@ -125,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,