calmlens 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b99a6fc15b38b4dd664a1df33e33eb8943cbd57483e16d7b7224f93cbc23d2a1
-  data.tar.gz: 668bf0e79e7fad1838be8d4e3c0bc536a379ea0de4cf3943a97057ed5025a72a
+  metadata.gz: 5fd7cb8e811f68c6be7989deb980a259d4a5643bc6f4402324c64236d258661b
+  data.tar.gz: f5e03fc720335e9c2ee2116549ddad9407a627449aed230f31eacf9a31743a3d
 SHA512:
-  metadata.gz: 00023a2b77c5dd78ebd7f0563ab9d152bede63882abc80c7a3e47d667f8e2d3ec54bade2c18fa4bd901167da1e8e3b7be2181491d1b3d5d1700bca568403d6ba
-  data.tar.gz: 7e8a4bcab13c13c6278169e15a54bec41a9fc5849c366dbff1ef0208b6fceeeece777c157c52ea2286bfcca2135c64e41c8b878c6456e534fce51fd368dd61fe
+  metadata.gz: ea06ee7b551c7e4a4336f3fb972e0e1181a55b5a148cb89c3b281dff789efe60289db280c18ffe700f1e883f763be60b10560b6a8321773c776aa40df2c57c13
+  data.tar.gz: b50571100307aaa792130cf4ca1d980232185613d9376a244b7857a7f052e0e43ffcbaa584fa661e869d349c3971e9d5199a07ac053844ee3ddbaa496db5aa81

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.
     #
@@ -395,13 +403,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 +460,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 +502,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 +512,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/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/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]