calmlens 0.18.3 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c938e439d92c33cdb3117354d680f702856acd600a262b41e221913effd2af9
-  data.tar.gz: a5b8999981f5fa0f5586f6eeaad4f2293011a25673f985622d70a2b7c6e48afd
+  metadata.gz: b3b2b65d6e8ec874bb4971fd4e4568e6cc424ecce6f060c6ce796bc2eb1a1c6d
+  data.tar.gz: 54a14554c90bec933b2ebaf0482918f3902497c6bdff6d8204e6b374fb881aab
 SHA512:
-  metadata.gz: cccc112f1003066fcbb1faa9e7fbcb729be199e70cb8869b632b3f6f50ce71ce67163baf61f88cdbde14f0cfc4c718dd7852a730dc77559c8904c81fecbefeb6
-  data.tar.gz: 1d74c52c7ba36c8a7db31d6647579c698fe27f573a7662bc26108fb2864d647b6ee9453419aa802ef0f3da6f3867b0df563c42b7900e2b672f219d2c257104e9
+  metadata.gz: 899100986bd5d7534a535a92f1af8c91a06fe8eadd123dfb9ef03a63d22193536c6d3bdaf72936905bee03379e88a3bb53e8197ae259fddec8b32e1d0eb951b8
+  data.tar.gz: 33d8fa683ba8d59117f9be22611f0ba5a12b4b2d557a4bbf61cdfd3b782f1d4186a3197bdaf3e26df8e0ff07c8ed53ca79e0bdeb84feae3d1f9ce904976ae7c6

data/README.md

@@ -60,7 +60,7 @@ New statuses and fields may appear in later API versions. The SDK returns them u
 
 - [Moderate text, images, documents, audio, video and websites](https://calmlens.com/docs/sdk/ruby#moderate-content), and [read classification results](https://calmlens.com/docs/guides/classification-results).
 - [Wait for a queued decision](https://calmlens.com/docs/sdk/ruby#waiting-for-a-decision) or [receive it by webhook](https://calmlens.com/docs/guides/webhooks).
-- [Stream uploads from any IO](https://calmlens.com/docs/sdk/ruby/reference#upload-content) and send [multipart uploads](https://calmlens.com/docs/guides/multipart-uploads).
+- [Stream uploads from any IO](https://calmlens.com/docs/sdk/ruby/reference#upload-content). Content larger than `part_size_bytes:` (8 MiB) that can be read again, such as a String or a File, goes in [parts](https://calmlens.com/docs/guides/multipart-uploads) automatically, each retried on its own and resumable with the same idempotency key.
 - [Moderate replies with their conversation](https://calmlens.com/docs/sdk/ruby/reference#conversation-context).
 - [Sign upload tokens for browser uploads](https://calmlens.com/docs/sdk/ruby/reference#upload-tokens) through [upload presets](https://calmlens.com/docs/guides/upload-presets).
 - [Record reviewer decisions](https://calmlens.com/docs/sdk/ruby/reference#reviewer-decisions) and [explain a decision](https://calmlens.com/docs/sdk/ruby#methods).
@@ -77,6 +77,8 @@ 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.
+
 ## Links
 
 - [Documentation](https://calmlens.com/docs/sdk/ruby)

data/lib/calmlens/assets.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module CalmLens
   # Uploads, moderation and management of assets. Reach it through {ServerClient#assets}.
   #
@@ -10,10 +12,19 @@ module CalmLens
   # later appear as they are, so compare `classification.moderation.status` and similar values with known strings
   # and treat anything else as not ready.
   class Assets < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'assets'
+
     SUBMIT_QUERY_KEYS = %w[name description processingOptions visibility metadata authorId context externalId externalUrl
                            folderId uploadPresetId].freeze
-    MIN_MULTIPART_IMAGE_BYTES = 10 * 1024 * 1024
     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.
+    MAX_DIRECT_IMAGE_BYTES = 10 * 1024 * 1024
+    MAX_MEDIA_BYTES = 50 * 1024 * 1024
+    MAX_FILE_BYTES = 5000 * 1024 * 1024
+    # The longest `idempotency_key` of an upload sent in parts: each part's key adds `:part-<n>`.
+    MAX_SPLIT_IDEMPOTENCY_KEY_LENGTH = 240
     # The moderation status before a decision; {#wait_for_decision} returns once an asset has any
     # other, or once its classification status is in {FINISHED_PROCESSING_STATUSES}.
     PENDING_MODERATION_STATUS = 'pending'
@@ -22,7 +33,7 @@ module CalmLens
     DECISION_POLL_FIRST_DELAY = 0.5
     # Each wait between decision checks is this many times the one before, up to DECISION_POLL_MAX_DELAY.
     DECISION_POLL_FACTOR = 1.5
-    DECISION_POLL_MAX_DELAY = 5.0
+    DECISION_POLL_MAX_DELAY = 2.0
     DEFAULT_DECISION_TIMEOUT = 60
     # The lifetime of a signed URL when none is given: 15 minutes.
     DEFAULT_SIGNED_URL_SECONDS = 15 * 60
@@ -40,7 +51,7 @@ module CalmLens
     # @option options [Integer] :limit
     # @return [Hash] `{'query', 'items' => [{'asset', 'score', 'matchedFields'}], 'semanticStatus'}`
     def search(options = {})
-      call(options) { |api, request| request('GET', project('assets/search'), query: api, request_options: request) }
+      call(options, __method__) { |api, request| request('GET', project('assets/search'), query: api, request_options: request) }
     end
 
     # Lists one page of assets.
@@ -50,7 +61,7 @@ module CalmLens
     # @option options [Array<Hash>] :ordering `[{field: 'createdAt', direction: 'desc'}]`
     # @return [Hash] a cursor page: items, nextCursor, hasMore, pageSize and ordering.
     def list(options = {})
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('GET', project('assets'), query: api, request_options: request)
       end
     end
@@ -62,7 +73,7 @@ module CalmLens
     def each(options = {}, &block)
       return enum_for(:each, options) unless block
 
-      api, request = call(options) { |*split| split }
+      api, request = call(options, __method__) { |*split| split }
       listing = pages(api['cursor']) { |index| list(api.merge('cursor' => index, 'request_options' => request)) }
       listing.each { |page| page['items'].each(&block) }
       nil
@@ -72,7 +83,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [Hash] a page like {#list}
     def list_children(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         query = without(api, 'assetId')
         request('GET', "/assets/#{Internal.segment(api['assetId'])}/children", query: query, request_options: request)
       end
@@ -85,7 +96,7 @@ module CalmLens
     def each_child(options, &block)
       return enum_for(:each_child, options) unless block
 
-      api, request = call(options) { |*split| split }
+      api, request = call(options, __method__) { |*split| split }
       listing = pages(api['cursor']) { |index| list_children(api.merge('cursor' => index, 'request_options' => request)) }
       listing.each { |page| page['items'].each(&block) }
       nil
@@ -94,7 +105,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [Hash] the asset
     def retrieve(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('GET', "/assets/#{Internal.segment(api['assetId'])}", request_options: request)
       end
     end
@@ -102,7 +113,7 @@ module CalmLens
     # Waits until an asset's `classification.moderation.status` is no longer `pending` (`allowed`,
     # `limited`, `age-restricted`, `blocked` or `purged`), or its `classification.status` is `failed`, and returns
     # the asset. It retrieves the asset, waiting 0.5 seconds before the second check and 1.5 times
-    # longer each time after that, up to 5 seconds.
+    # longer each time after that, up to 2 seconds.
     # Webhooks report decisions without polling.
     #
     # `timeout:` is the whole wait in seconds; `request_options: {timeout:}` still limits each request.
@@ -113,7 +124,7 @@ module CalmLens
     # @raise [TimeoutError] `sdk/timeout` when no decision arrives in time; `details` holds
     #   `'assetId'` and the last `'classificationStatus'` and `'moderationStatus'`.
     def wait_for_decision(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         timeout = api.fetch('timeout', DEFAULT_DECISION_TIMEOUT)
         unless timeout.is_a?(Numeric) && timeout.real? && timeout.to_f.finite? && !timeout.negative?
           raise Internal.invalid('timeout must be a non-negative number of seconds')
@@ -127,7 +138,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [Hash] the updated asset
     def update(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('PATCH', "/assets/#{Internal.segment(api['assetId'])}", body: without(api, 'assetId'),
                                                                         request_options: request)
       end
@@ -137,7 +148,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [Hash] the asset
     def retry(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('POST', "/assets/#{Internal.segment(api['assetId'])}/retry", request_options: request)
       end
     end
@@ -154,7 +165,7 @@ module CalmLens
     # @option options [Boolean] :confirm_purge must be true to purge
     # @return [Hash] the asset
     def decide(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('POST', "/assets/#{Internal.segment(api['assetId'])}/decision", body: without(api, 'assetId'),
                                                                                 request_options: request)
       end
@@ -168,7 +179,7 @@ module CalmLens
     # @option options [Boolean] :rerun
     # @return [Hash] the asset
     def explain(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('POST', "/assets/#{Internal.segment(api['assetId'])}/explain",
                 body: api['rerun'] ? { 'rerun' => true } : {}, request_options: request)
       end
@@ -179,7 +190,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [Hash] the asset
     def delete_content(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('DELETE', "/assets/#{Internal.segment(api['assetId'])}/content", request_options: request)
       end
     end
@@ -188,7 +199,7 @@ module CalmLens
     # @option options [String] :asset_id
     # @return [nil]
     def delete(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('DELETE', "/assets/#{Internal.segment(api['assetId'])}", request_options: request)
         nil
       end
@@ -203,7 +214,7 @@ module CalmLens
     # @option options [String] :operation one of {BATCH_OPERATIONS}
     # @return [Hash] `{'queued' => true}`
     def batch(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         ids = api['assetIds']
         unless ids.is_a?(Array) && ids.size.between?(1, MAX_BATCH_ASSETS)
           raise Internal.invalid("asset_ids must list 1 to #{MAX_BATCH_ASSETS} asset IDs")
@@ -221,7 +232,7 @@ module CalmLens
     # @option options [String, nil] :folder_id
     # @return [Hash] the asset
     def move(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('POST', "/assets/#{Internal.segment(api['assetId'])}/move",
                 body: { 'folderId' => Internal.required(api, 'folderId') }, request_options: request)
       end
@@ -232,11 +243,11 @@ module CalmLens
     # @option options [String] :resource `rendered` (the API's default) or `original`, which takes no lens or transform
     # @option options [Integer] :expires_in_seconds default 900
     # @option options [String] :lens a lens identifier
-    # @option options [String, Hash, Array<Hash>] :transform a selector String or structured steps,
-    #   as for {CDN#get_asset_url}; a lens runs before any additional transforms
+    # @option options [String, Hash] :transform a selector String or structured options, as for
+    #   {CDN#get_asset_url}; they replace the lens's options of the same name
     # @return [Hash] `{'url', 'expiresAt'}`
     def create_signed_url(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         path = "/assets/#{Internal.segment(api['assetId'])}/signed-url"
         body = { 'expiresInSeconds' => DEFAULT_SIGNED_URL_SECONDS }.merge(without(api, 'assetId'))
         check_signed_url(body)
@@ -258,6 +269,13 @@ module CalmLens
     #
     # The request carries an `Idempotency-Key` (generated unless you pass
     # `request_options: {idempotency_key:}`), so a retried upload never creates a second asset.
+    #
+    # `content:` larger than the client's `part_size_bytes` (8 MiB by default) whose size is known and
+    # that can be read again (a binary String, base64, or a File, StringIO or other seekable IO) is
+    # sent as a multipart upload in parts of that size. Each part carries the key
+    # `<idempotency_key>:part-<n>` and is retried on its own; calling again with the same
+    # `idempotency_key` (at most 240 characters) resumes an interrupted upload. Pipes, sockets and
+    # text are sent in one request.
     # @option options [String] :name
     # @option options [Hash] :content
     # @option options [Hash] :part `{type:, data:, is_final:}` for the first multipart part
@@ -270,7 +288,7 @@ module CalmLens
     #   {ModerationContext::USED_ITEMS} that fit in {ModerationContext::USED_CHARACTERS} characters.
     # @return [Hash] the asset
     def create(options)
-      call(options) { |api, request| submit(api, request, true) }
+      call(options, __method__) { |api, request| submit(api, request, true) }
     end
 
     # Uploads content and waits for the moderation decision where the content type supports it.
@@ -279,7 +297,7 @@ module CalmLens
     #   `allowed` or `limited` (reduce the reach of `limited` assets). Serve `age-restricted` assets
     #   only behind your own age check, through signed URLs.
     def classify(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         content = api['content']
         if content.is_a?(Hash) && content.key?('plainText') && (!content['plainText'].is_a?(String) || content['plainText'].strip.empty?)
           raise Internal.invalid('Text to classify must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
@@ -296,8 +314,8 @@ module CalmLens
     # @option options [Boolean] :queue
     # @return [Hash] the asset; `classification.status` stays `uploading` until the final part.
     def upload_part(options)
-      call(options) do |api, request|
-        path = "/assets/#{Internal.segment(api['assetId'])}/part"
+      call(options, __method__) do |api, request|
+        Internal.segment(api['assetId'])
         part = api['part']
         raise Internal.invalid('part is required') unless part.is_a?(Hash)
 
@@ -308,10 +326,7 @@ module CalmLens
         end
 
         body = UploadBody.from(part, multipart: true, part_size: !@session.defer_upload_checks)
-        query = { 'partNumber' => number, 'isFinal' => part.fetch('isFinal', false), 'sizeInBytes' => body.size }
-        query['queue'] = api['queue'] if api.key?('queue')
-        expect_asset(request('POST', path, query: query, raw: body, idempotent: true, request_options: request, upload: true,
-                                           headers: { 'Content-Type' => 'application/octet-stream', 'X-CalmLens-Upload' => 'part' }))
+        send_part(api['assetId'], number, part.fetch('isFinal', false), body, api.fetch('queue', nil), request)
       end
     end
 
@@ -365,6 +380,9 @@ module CalmLens
       end
 
       body = UploadBody.from(content, multipart: multipart, part_size: !@session.defer_upload_checks)
+      return upload_in_parts(options, request_options, queue, mime, body) if !multipart && splits?(content, body)
+
+      check_direct_size(mime, body.size) unless multipart || @session.defer_upload_checks
       query = options.slice(*SUBMIT_QUERY_KEYS).merge('queue' => queue, 'contentType' => content['type'],
                                                       'sizeInBytes' => body.size)
       query.merge!(first_part_query(options, content, mime, body)) if multipart
@@ -374,6 +392,75 @@ module CalmLens
                            headers: { 'Content-Type' => content['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.
+    def splits?(content, body)
+      !content.key?('plainText') && !body.size.nil? && body.replayable? && body.size > @session.part_size_bytes
+    end
+
+    # Uploads `body` as a multipart upload of `part_size_bytes` parts and returns the final part's
+    # asset. Part `n` after the first carries the key `<key>:part-<n>`, so repeating the call with
+    # the same key replays the parts the API already has and sends the rest.
+    def upload_in_parts(options, request_options, queue, mime, body)
+      key = request_options[:idempotency_key] || SecureRandom.uuid
+      if key.length > MAX_SPLIT_IDEMPOTENCY_KEY_LENGTH
+        raise Internal.invalid("idempotency_key can have at most #{MAX_SPLIT_IDEMPOTENCY_KEY_LENGTH} characters " \
+                               'for content uploaded in parts')
+      end
+      unless @session.defer_upload_checks
+        mime.start_with?('image/') ? check_image_size(body.size) : check_direct_size(mime, body.size)
+      end
+
+      total = body.size
+      part_size = @session.part_size_bytes
+      count = (total + part_size - 1) / part_size
+      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('queue' => queue, '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' }))
+      send_remaining_parts(asset, count, piece, key, request_options)
+    end
+
+    # Sends parts 2 to `count`. A part the API already has (its response was lost) is skipped, and a
+    # final part that finds the upload completed reads the asset back.
+    def send_remaining_parts(asset, count, piece, key, request_options)
+      id = asset['id']
+      number = 2
+      while number <= count
+        final = number == count
+        begin
+          asset = send_part(id, number, final, piece.call(number), nil,
+                            request_options.merge(idempotency_key: "#{key}:part-#{number}"))
+        rescue Error => e
+          expected = e.details.is_a?(Hash) ? e.details['expectedPartNumber'] : nil
+          if e.code == ErrorCodes::INVALID_UPLOAD_PART_NUMBER && expected.is_a?(Integer) && expected > number && expected <= count
+            number = expected
+            next
+          end
+          if final && e.code == ErrorCodes::UPLOAD_NOT_OPEN
+            return retrieve('assetId' => id, 'request_options' => request_options.except(:idempotency_key))
+          end
+
+          raise
+        end
+        number += 1
+      end
+      asset
+    end
+
+    def send_part(asset_id, number, final, body, queue, request_options)
+      query = { 'partNumber' => number, 'isFinal' => final, 'sizeInBytes' => body.size }
+      query['queue'] = queue unless queue.nil?
+      headers = { 'Content-Type' => 'application/octet-stream', 'X-CalmLens-Upload' => 'part' }
+      expect_asset(request('POST', "/assets/#{Internal.segment(asset_id)}/part", query: query, raw: body, idempotent: true,
+                                                                                 request_options: request_options, upload: true,
+                                                                                 headers: headers))
+    end
+
     # Keeps only the earlier posts CalmLens uses, which keeps a raw upload's query short.
     def with_used_context(options)
       return options unless options.key?('context')
@@ -392,7 +479,7 @@ module CalmLens
       end
 
       final = content.fetch('isFinal', false)
-      check_image_size(total || body.size, total || final) if mime.start_with?('image/') && !@session.defer_upload_checks
+      check_image_size(total || body.size) if mime.start_with?('image/') && !@session.defer_upload_checks
       { 'partNumber' => 1, 'isFinal' => final, 'totalSizeInBytes' => total }
     end
 
@@ -423,25 +510,38 @@ module CalmLens
 
     def check_mime(type)
       mime = type.to_s.split(';').first.to_s.strip.downcase
-      if mime.empty? || mime == 'application/octet-stream' || mime.start_with?('multipart/')
-        raise Internal.invalid("#{mime} is not a valid upload file type. Uploads must use a concrete file MIME type " \
-                               'that CalmLens can store and process, such as image/png, image/jpeg, ' \
-                               'application/pdf, or text/plain.', ErrorCodes::INVALID_UPLOAD_MIME_TYPE)
+      unless Internal.accepted_upload_mime_type?(mime)
+        raise InvalidArgumentError.new(ErrorCodes::INVALID_UPLOAD_MIME_TYPE,
+                                       "#{mime} is not a valid upload file type. Uploads must use a concrete file MIME " \
+                                       'type that CalmLens can store and process, such as image/png, image/jpeg, ' \
+                                       'application/pdf, or text/plain.', details: { 'mimeType' => type })
       end
       raise Internal.invalid('Content type cannot contain line breaks') unless type.match?(Internal::HEADER_VALUE)
 
       mime
     end
 
-    # Multipart images total 10MB to 20MB. With a declared total both bounds apply from the start.
-    def check_image_size(size, complete)
-      if size > MAX_MULTIPART_IMAGE_BYTES
-        raise Internal.invalid('Multipart image uploads cannot exceed 20MB.',
-                               ErrorCodes::MULTIPART_IMAGE_TOO_LARGE)
-      end
-      return unless complete && size < MIN_MULTIPART_IMAGE_BYTES
+    # Refuses one-request content whose known size is over the API's limit for its type, before
+    # any of it is sent.
+    def check_direct_size(mime, size)
+      return if size.nil?
+
+      limit, message = if mime.start_with?('image/')
+                         [MAX_DIRECT_IMAGE_BYTES, 'Images uploaded in one request can be at most 10 MiB; upload larger images in parts']
+                       elsif mime.start_with?('audio/', 'video/')
+                         [MAX_MEDIA_BYTES, 'Audio and video files can be at most 50 MiB']
+                       else
+                         [MAX_FILE_BYTES, 'Files can be at most 5,000 MiB']
+                       end
+      raise Internal.invalid(message, ErrorCodes::FILE_TOO_LARGE) if size > limit
+    end
+
+    # Images in parts total at most 20 MiB, at any size below that; a declared total is checked
+    # from the start.
+    def check_image_size(size)
+      return unless size > MAX_MULTIPART_IMAGE_BYTES
 
-      raise Internal.invalid('Multipart image uploads must total at least 10MB.', ErrorCodes::MULTIPART_IMAGE_TOO_SMALL)
+      raise Internal.invalid('Multipart image uploads cannot exceed 20MB.', ErrorCodes::MULTIPART_IMAGE_TOO_LARGE)
     end
   end
 end

data/lib/calmlens/cdn.rb

@@ -3,6 +3,9 @@
 module CalmLens
   # CDN URLs and authenticated content delivery. Reach it through {ServerClient#cdn}.
   class CDN < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'cdn'
+
     RESOURCES = %w[original rendered placeholder].freeze
     private_constant :RESOURCES
 
@@ -13,15 +16,18 @@ module CalmLens
     #   takes a lens or transform. A placeholder is a small blurred PNG that the CDN serves publicly for every
     #   asset whatever its visibility or moderation status; it needs no age confirmation.
     # @option options [String] :lens a lens identifier
-    # @option options [String, Hash, Array<Hash>] :transform a selector such as `width=200,fit=cover`,
-    #   or structured steps: `{type: 'imageTransform', options: {width: 200}}` or an Array of them
+    # @option options [String, Hash] :transform options applied in one pass: a selector such as
+    #   `width=200,fit=cover`, or structured options such as `{width: 200, fit: 'cover'}`. With a lens,
+    #   they replace the lens's options of the same name
     # @option options [Hash] :viewer_claims viewer assertions, such as `{age_confirmed: true}`, sent as a JSON
     #   `viewerClaims` query parameter. 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.
+    #   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 public URL. To control who loads an age-restricted
+    #   asset, make it private and include the claim in a signed URL.
     # @return [String]
     def get_asset_url(options)
-      call(options) { |api, _request| url(api) }
+      call(options, __method__) { |api, _request| url(api) }
     end
 
     # Fetches content from the CDN with the client's API key.
@@ -44,7 +50,7 @@ module CalmLens
     #     end
     #   end
     def serve(options, &)
-      method, url, headers, request = call(options) do |api, request_options|
+      method, url, headers, request = call(options, __method__) do |api, request_options|
         init = api.fetch('init', {})
         raise Internal.invalid('init must be a Hash') unless init.is_a?(Hash)
 
@@ -68,9 +74,10 @@ module CalmLens
 
       url = "#{@session.cdn_base_url}/assets/#{Internal.segment(@session.project_id)}/" \
             "#{Internal.segment(api['assetIdentifier'])}/#{resource}"
-      url += "/@#{Internal.segment(api['lens'])}" if api['lens']
       transform = api['transform']
-      url += "/#{Transforms.path(transform)}" unless transform.nil? || transform == ''
+      selector = [("@#{Internal.segment(api['lens'])}" if api['lens']),
+                  (Transforms.path(transform) unless transform.nil? || transform == '')].compact.join(',')
+      url += "/#{selector}" unless selector.empty?
 
       claims = api['viewerClaims']
       if !claims.nil? && (!claims.is_a?(Hash) || (claims.key?('ageConfirmed') && ![true, false].include?(claims['ageConfirmed'])))

data/lib/calmlens/error_codes.rb

@@ -10,6 +10,8 @@ module CalmLens
     INVALID_VIEWER_REGION = 'viewer/invalid-region'
     VIEWER_REGION_REQUIRED = 'viewer/region-required'
     REGIONAL_EVIDENCE_REQUIRED = 'asset/regional-evidence-required'
+    SIGNED_URL_EXPIRED = 'signed-url/expired'
+    SIGNED_URL_INVALID = 'signed-url/invalid'
     INVALID_TYPE = 'validation/invalid-type'
     TOO_SMALL = 'validation/too-small'
     TOO_BIG = 'validation/too-big'
@@ -37,9 +39,11 @@ module CalmLens
     API_KEY_NOT_ACCEPTED = 'auth/api-key-not-accepted'
     PERMISSION_DENIED = 'auth/permission-denied'
     FILE_TOO_LARGE = 'upload/file-too-large'
-    MULTIPART_IMAGE_TOO_SMALL = 'upload/multipart-image-too-small'
     MULTIPART_IMAGE_TOO_LARGE = 'upload/multipart-image-too-large'
     IMAGE_EXCEEDED_MAX_DIMENSIONS = 'upload/image-exceeded-max-dimensions'
+    IMAGE_INVALID_INPUT = 'image/invalid-input'
+    IMAGE_UNSUPPORTED_FORMAT = 'image/unsupported-format'
+    IMAGE_INPUT_LIMIT = 'image/input-limit'
     UPLOAD_LIMIT_EXCEEDED = 'upload/limit-exceeded'
     SPEND_LIMIT_REACHED = 'upload/spend-limit-reached'
     INVALID_UPLOAD_MIME_TYPE = 'upload/invalid-mime-type'
@@ -80,6 +84,15 @@ module CalmLens
     HASH_LIST_LIMIT_REACHED = 'hash-list/limit-reached'
     HASH_LIST_ENTRY_LIMIT_REACHED = 'hash-list/entry-limit-reached'
     HASH_LIST_ASSET_NOT_HASHED = 'hash-list/asset-not-hashed'
+    POLICY_NOT_FOUND = 'policy/not-found'
+    POLICY_REVISION_CONFLICT = 'policy/revision-conflict'
+    POLICY_PROJECTS_CHANGED = 'policy/projects-changed'
+    POLICY_IN_USE = 'policy/in-use'
+    POLICY_USED_BY_ANOTHER_PROJECT = 'policy/used-by-another-project'
+    POLICY_NO_PRESET = 'policy/no-preset'
+    POLICY_PRESET_VERSION_CONFLICT = 'policy/preset-version-conflict'
+    POLICY_PRESET_UPDATE_UNAVAILABLE = 'policy/preset-update-unavailable'
+    POLICY_AUTOMATIC_UPDATES_UNAVAILABLE = 'policy/automatic-updates-unavailable'
     UPLOAD_PRESET_NOT_FOUND = 'upload-preset/not-found'
     UPLOAD_PRESET_DISABLED = 'upload-preset/disabled'
     UPLOAD_PRESET_TOKEN_REQUIRED = 'upload-preset/token-required'
@@ -112,6 +125,8 @@ module CalmLens
       'viewer/invalid-region' => 400,
       'viewer/region-required' => 403,
       'asset/regional-evidence-required' => 403,
+      'signed-url/expired' => 403,
+      'signed-url/invalid' => 403,
       'validation/invalid-type' => 400,
       'validation/too-small' => 400,
       'validation/too-big' => 400,
@@ -139,9 +154,11 @@ module CalmLens
       'auth/api-key-not-accepted' => 403,
       'auth/permission-denied' => 403,
       'upload/file-too-large' => 400,
-      'upload/multipart-image-too-small' => 400,
       'upload/multipart-image-too-large' => 400,
       'upload/image-exceeded-max-dimensions' => 400,
+      'image/invalid-input' => 422,
+      'image/unsupported-format' => 422,
+      'image/input-limit' => 422,
       'upload/limit-exceeded' => 403,
       'upload/spend-limit-reached' => 402,
       'upload/invalid-mime-type' => 400,
@@ -182,6 +199,15 @@ module CalmLens
       'hash-list/limit-reached' => 409,
       'hash-list/entry-limit-reached' => 409,
       'hash-list/asset-not-hashed' => 409,
+      'policy/not-found' => 404,
+      'policy/revision-conflict' => 409,
+      'policy/projects-changed' => 409,
+      'policy/in-use' => 409,
+      'policy/used-by-another-project' => 409,
+      'policy/no-preset' => 400,
+      'policy/preset-version-conflict' => 409,
+      'policy/preset-update-unavailable' => 409,
+      'policy/automatic-updates-unavailable' => 409,
       'upload-preset/not-found' => 404,
       'upload-preset/disabled' => 403,
       'upload-preset/token-required' => 401,

data/lib/calmlens/events.rb

@@ -3,13 +3,16 @@
 module CalmLens
   # The project's events feed. Reach it through {ServerClient#events}.
   class Events < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'events'
+
     # Lists events after a cursor, oldest first. Without `cursor`, returns no events and a
     # `nextCursor` for the current time: save it, then pass each response's `nextCursor` as `cursor`.
     # @option options [String] :cursor the `nextCursor` of a previous response
     # @option options [Integer] :page_size 1 to 100, default 50
     # @return [Hash] `{'items', 'nextCursor', 'hasMore'}`; `nextCursor` is never nil
     def list(options = {})
-      call(options) { |api, request| request('GET', project('events'), query: api, request_options: request) }
+      call(options, __method__) { |api, request| request('GET', project('events'), query: api, request_options: request) }
     end
 
     # Iterates pages from `cursor` until `hasMore` is false. Persist each page's `nextCursor` once its
@@ -20,7 +23,7 @@ module CalmLens
     def each_page(options = {})
       return enum_for(:each_page, options) unless block_given?
 
-      api, request = call(options) { |*split| split }
+      api, request = call(options, __method__) { |*split| split }
       sent = api.key?('cursor') ? [api['cursor']] : []
       loop do
         page = list(api.merge('request_options' => request))

data/lib/calmlens/folders.rb

@@ -3,6 +3,9 @@
 module CalmLens
   # Folders organise a project's assets. Reach it through {ServerClient#folders}.
   class Folders < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'folders'
+
     # Lists one page of child folders, sorted by name unless `ordering` says otherwise.
     # @option options [String] :parent_id list this folder's children; omit for the project root
     # @option options [String] :cursor the previous page's `nextCursor`
@@ -11,7 +14,7 @@ module CalmLens
     # @option options [String] :search only children whose name contains it
     # @return [Hash] a cursor page (items, nextCursor, hasMore, pageSize, ordering) with ancestors.
     def list(options = {})
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         response = request('GET', project('folders'), query: api, request_options: request)
         valid = response.is_a?(Hash) && response['items'].is_a?(Array) && response['ancestors'].is_a?(Array) &&
                 [true, false].include?(response['hasMore'])
@@ -25,13 +28,13 @@ module CalmLens
     # @option options [String, nil] :parent_id
     # @return [Hash] the folder
     def create(options)
-      call(options) { |api, request| request('POST', project('folders'), body: api, request_options: request) }
+      call(options, __method__) { |api, request| request('POST', project('folders'), body: api, request_options: request) }
     end
 
     # @option options [String] :folder_id
     # @return [Hash] the folder
     def retrieve(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('GET', "/folders/#{Internal.segment(api['folderId'])}", request_options: request)
       end
     end
@@ -40,7 +43,7 @@ module CalmLens
     # @option options [String] :name
     # @return [Hash] the folder
     def update(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('PATCH', "/folders/#{Internal.segment(api['folderId'])}", body: without(api, 'folderId'),
                                                                           request_options: request)
       end
@@ -51,7 +54,7 @@ module CalmLens
     # @option options [String, nil] :parent_id
     # @return [Hash] the folder
     def move(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('POST', "/folders/#{Internal.segment(api['folderId'])}/move",
                 body: { 'parentId' => Internal.required(api, 'parentId') }, request_options: request)
       end
@@ -61,7 +64,7 @@ module CalmLens
     # @option options [String] :folder_id
     # @return [nil]
     def delete(options)
-      call(options) do |api, request|
+      call(options, __method__) do |api, request|
         request('DELETE', "/folders/#{Internal.segment(api['folderId'])}", request_options: request)
         nil
       end