calmlens 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b2b65d6e8ec874bb4971fd4e4568e6cc424ecce6f060c6ce796bc2eb1a1c6d
-  data.tar.gz: 54a14554c90bec933b2ebaf0482918f3902497c6bdff6d8204e6b374fb881aab
+  metadata.gz: 5fd7cb8e811f68c6be7989deb980a259d4a5643bc6f4402324c64236d258661b
+  data.tar.gz: f5e03fc720335e9c2ee2116549ddad9407a627449aed230f31eacf9a31743a3d
 SHA512:
-  metadata.gz: 899100986bd5d7534a535a92f1af8c91a06fe8eadd123dfb9ef03a63d22193536c6d3bdaf72936905bee03379e88a3bb53e8197ae259fddec8b32e1d0eb951b8
-  data.tar.gz: 33d8fa683ba8d59117f9be22611f0ba5a12b4b2d557a4bbf61cdfd3b782f1d4186a3197bdaf3e26df8e0ff07c8ed53ca79e0bdeb84feae3d1f9ce904976ae7c6
+  metadata.gz: ea06ee7b551c7e4a4336f3fb972e0e1181a55b5a148cb89c3b281dff789efe60289db280c18ffe700f1e883f763be60b10560b6a8321773c776aa40df2c57c13
+  data.tar.gz: b50571100307aaa792130cf4ca1d980232185613d9376a244b7857a7f052e0e43ffcbaa584fa661e869d349c3971e9d5199a07ac053844ee3ddbaa496db5aa81

data/README.md

@@ -16,6 +16,8 @@ gem "calmlens"
 
 The gem has no runtime dependencies: it uses only the standard library (Net::HTTP, JSON, OpenSSL). It ships YARD documentation and RBS signatures in `sig/`, so Steep and other RBS tools can check your calls and the response keys you read.
 
+Versions follow semantic versioning: see [Versioning and support](https://calmlens.com/docs/sdk#versioning-and-support).
+
 ## Quick start
 
 Create an API key and copy your project ID in the CalmLens portal, and keep both on your server.
@@ -67,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).
@@ -77,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.
+`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,30 +15,30 @@ module CalmLens
     # 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
+    # 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.
     MAX_DIRECT_IMAGE_BYTES = 10 * 1024 * 1024
     MAX_MEDIA_BYTES = 50 * 1024 * 1024
     MAX_FILE_BYTES = 5000 * 1024 * 1024
+    # Audio and video sent in parts can be up to 2 GiB; the API holds free uploads, made before
+    # billing is set up, to MAX_MEDIA_BYTES itself.
+    MAX_LONG_MEDIA_BYTES = 2 * 1024 * 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'
-    # Processing statuses after which no decision will arrive without a retry.
-    FINISHED_PROCESSING_STATUSES = %w[failed].freeze
+    # The classification statuses of a settled asset: `completed` (with its decision in
+    # `classification.moderation.status`) or `failed`. {#wait_for_decision} returns at the first.
+    SETTLED_STATUSES = %w[completed failed].freeze
     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 = 2.0
     DEFAULT_DECISION_TIMEOUT = 60
-    # The lifetime of a signed URL when none is given: 15 minutes.
-    DEFAULT_SIGNED_URL_SECONDS = 15 * 60
-    # The longest signed URL lifetime the API accepts: 24 hours.
-    MAX_SIGNED_URL_SECONDS = 24 * 60 * 60
     # The operations {#batch} runs: `delete` deletes each asset with its child assets and stored
     # content; `remove-content` removes its stored content and keeps the record.
     BATCH_OPERATIONS = %w[delete remove-content].freeze
@@ -48,18 +48,20 @@ module CalmLens
     # Searches assets by meaning or keyword.
     # @option options [String] :query
     # @option options [String] :mode `hybrid`, `semantic` or `keyword`
-    # @option options [Integer] :limit
+    # @option options [Integer] :page_size how many results, 1 to 20 (default 10)
     # @return [Hash] `{'query', 'items' => [{'asset', 'score', 'matchedFields'}], 'semanticStatus'}`
     def search(options = {})
       call(options, __method__) { |api, request| request('GET', project('assets/search'), query: api, request_options: request) }
     end
 
-    # Lists one page of assets.
+    # Lists one page of assets, newest first unless `sort` says otherwise.
     # @option options [String] :cursor from the previous page
     # @option options [Integer] :page_size 1 to 100, default 50
-    # @option options [String] :filter an RSQL filter such as `classification.moderation.status==allowed`
-    # @option options [Array<Hash>] :ordering `[{field: 'createdAt', direction: 'desc'}]`
-    # @return [Hash] a cursor page: items, nextCursor, hasMore, pageSize and ordering.
+    # @option options [String, nil] :filter an RSQL filter such as `classification.moderation.status==allowed`;
+    #   `folderId==fldr_…` lists one folder's assets and `folderId==null` the project root's
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`, such as `-createdAt,id`; `-createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
     def list(options = {})
       call(options, __method__) do |api, request|
         request('GET', project('assets'), query: api, request_options: request)
@@ -73,14 +75,14 @@ module CalmLens
     def each(options = {}, &block)
       return enum_for(:each, options) unless block
 
-      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
+      each_item(options, __method__, method(:list), &block)
     end
 
     # Lists one page of an asset's children, such as frames extracted from a video.
     # @option options [String] :asset_id
+    # @option options [String] :cursor
+    # @option options [Integer] :page_size
+    # @option options [String] :sort as for {#list}
     # @return [Hash] a page like {#list}
     def list_children(options)
       call(options, __method__) do |api, request|
@@ -89,6 +91,30 @@ module CalmLens
       end
     end
 
+    # Lists one page of an audio or video asset's findings timeline, in time order.
+    # `classification.moderation.timeline.segmentCount` says how many segments there are. Pass each
+    # page's `nextCursor` back unchanged; cursors are opaque.
+    # @option options [String] :asset_id
+    # @option options [String] :cursor
+    # @option options [Integer] :page_size
+    # @return [Hash] a cursor page of timeline segments: items, nextCursor and hasMore.
+    def list_timeline(options)
+      call(options, __method__) do |api, request|
+        query = without(api, 'assetId')
+        request('GET', project("assets/#{Internal.segment(api['assetId'])}/timeline"), query: query, request_options: request)
+      end
+    end
+
+    # Iterates every segment of an audio or video asset's findings timeline, in time order.
+    # @param options [Hash] the options of {#list_timeline}
+    # @yieldparam segment [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each_timeline_segment(options, &block)
+      return enum_for(:each_timeline_segment, options) unless block
+
+      each_item(options, __method__, method(:list_timeline), &block)
+    end
+
     # Iterates every child of an asset, fetching pages as needed.
     # @param options [Hash] the options of {#list_children}
     # @yieldparam asset [Hash]
@@ -96,10 +122,7 @@ module CalmLens
     def each_child(options, &block)
       return enum_for(:each_child, options) unless block
 
-      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
+      each_item(options, __method__, method(:list_children), &block)
     end
 
     # @option options [String] :asset_id
@@ -110,18 +133,19 @@ module CalmLens
       end
     end
 
-    # 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 2 seconds.
+    # Waits until an asset is settled, its `classification.status` `completed` (with its decision in
+    # `classification.moderation.status`) or `failed`, and returns the asset. A `queued` or `processing`
+    # asset is still waiting, even when a reviewer has already decided it. It retrieves the asset,
+    # waiting 0.5 seconds before the second check and 1.5 times 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.
     # To stop waiting early, run the call in a thread you can stop: it only sleeps and sends requests.
     # @option options [String] :asset_id
     # @option options [Numeric] :timeout seconds to wait for a decision (default 60)
-    # @return [Hash] the decided asset
-    # @raise [TimeoutError] `sdk/timeout` when no decision arrives in time; `details` holds
+    # @return [Hash] the settled asset
+    # @raise [TimeoutError] `sdk/timeout` when the asset isn't settled in time; `details` holds
     #   `'assetId'` and the last `'classificationStatus'` and `'moderationStatus'`.
     def wait_for_decision(options)
       call(options, __method__) do |api, request|
@@ -155,7 +179,7 @@ module CalmLens
 
     # Records a reviewer's decision, replacing the policy's: `classification.moderation.status`
     # becomes the decision, the decision and note join `classification.moderation.manualReviews` and
-    # the matching `asset.<status>` event is sent with `decided-by: reviewer`. An asset still pending
+    # the matching `asset.<status>` event is sent with the API key as its `actor`. An asset still pending
     # moderation can only be blocked or purged. Purging needs `confirm_purge: true` and the
     # `assets:delete` permission, and permanently deletes the stored content. Not retried: it carries
     # no `Idempotency-Key`.
@@ -173,8 +197,12 @@ module CalmLens
 
     # Completes the policy evidence behind a decided asset's moderation decision: the report's
     # `classification.moderation.explanationComplete` becomes `true` and every action stays as decided.
-    # With `rerun: true` the asset is moderated again with the project's current policy and returns
-    # in `processing`; use it when the policy changed since the decision (`asset/policy-changed`).
+    # With `rerun: true` the asset is moderated again with the project's current policy and an
+    # `asset.rerun-requested` event is recorded; use it when the policy changed since the decision
+    # (`asset/policy-changed`). The asset returns unchanged: it keeps its decision until the re-run's
+    # is stored, reported by `asset.classified` and `asset.<status>` events, and a failed re-run keeps
+    # it. A reviewed asset raises `asset/reviewed`, and one whose content is gone
+    # `asset/content-unavailable`.
     # @option options [String] :asset_id
     # @option options [Boolean] :rerun
     # @return [Hash] the asset
@@ -189,13 +217,14 @@ module CalmLens
     # `requested`); the record and classification results are kept.
     # @option options [String] :asset_id
     # @return [Hash] the asset
-    def delete_content(options)
+    def remove_content(options)
       call(options, __method__) do |api, request|
         request('DELETE', "/assets/#{Internal.segment(api['assetId'])}/content", request_options: request)
       end
     end
 
-    # Deletes the asset record and its stored content.
+    # Deletes the asset record and its stored content. An asset extracted from another (one with a
+    # `parentId`) raises `asset/child-not-deletable`: delete its parent instead.
     # @option options [String] :asset_id
     # @return [nil]
     def delete(options)
@@ -207,12 +236,14 @@ module CalmLens
 
     # Deletes up to 500 assets (`operation: 'delete'`) or removes their stored content
     # (`'remove-content'`) in one request. Every asset must exist in the project and the key needs
-    # `assets:delete` for its folder, or nothing is queued. Returns once the operation is queued; the
+    # `assets:delete` for its folder, and a deletion can't name an asset extracted from another
+    # (`asset/child-not-deletable`), or nothing is queued. Returns once the operation is queued; the
     # work runs in the background and records `asset.deleted` or `asset.content-removed` for each
-    # asset. Assets under a safety hold are skipped. Not retried: it carries no `Idempotency-Key`.
+    # asset, with a `batch-id` fact naming `batchId`. Assets under a safety hold are skipped. Not
+    # retried: it carries no `Idempotency-Key`.
     # @option options [Array<String>] :asset_ids 1 to 500 asset IDs
     # @option options [String] :operation one of {BATCH_OPERATIONS}
-    # @return [Hash] `{'queued' => true}`
+    # @return [Hash] `{'batchId', 'status' => 'queued', 'assetCount'}`
     def batch(options)
       call(options, __method__) do |api, request|
         ids = api['assetIds']
@@ -238,27 +269,8 @@ module CalmLens
       end
     end
 
-    # Creates a time-limited URL that delivers private content without an API key.
-    # @option options [String] :asset_id
-    # @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] :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, __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)
-        body['transform'] = Transforms.selector(body['transform']) if body.key?('transform')
-        request('POST', path,
-                body: body,
-                request_options: request)
-      end
-    end
-
-    # Uploads content and queues moderation; the call returns before classification finishes.
+    # Uploads content and returns without waiting for its decision (`wait=false`), with
+    # `classification.status` `queued`.
     # Watch for `asset.allowed`, `asset.limited`, `asset.age-restricted`, `asset.blocked` and
     # `asset.purged` events or retrieve the asset later.
     #
@@ -267,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.
     #
@@ -281,6 +298,7 @@ module CalmLens
     # @option options [Hash] :part `{type:, data:, is_final:}` for the first multipart part
     # @option options [Integer] :total_size_in_bytes the whole file's size, for multipart uploads
     # @option options [String] :url
+    # @option options [Array<String>] :tags tags for the asset, such as `['catalogue', 'backpacks']`
     # @option options [String] :author_id your identifier for who wrote the content; CalmLens only
     #   compares it with the author IDs in `context`, to tell which posts share a speaker.
     # @option options [Hash] :context `{items: [{text:, author_id:}]}`, earlier posts in the
@@ -288,7 +306,7 @@ module CalmLens
     #   {ModerationContext::USED_ITEMS} that fit in {ModerationContext::USED_CHARACTERS} characters.
     # @return [Hash] the asset
     def create(options)
-      call(options, __method__) { |api, request| submit(api, request, true) }
+      call(options, __method__) { |api, request| submit(api, request, false) }
     end
 
     # Uploads content and waits for the moderation decision where the content type supports it.
@@ -303,15 +321,17 @@ module CalmLens
           raise Internal.invalid('Text to classify must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
         end
 
-        submit(api, request, false)
+        submit(api, request, true)
       end
     end
 
     # Uploads a later part of a multipart upload started with {#create} or {#classify} and `part:`.
-    # The queue mode chosen at the start applies; pass `queue:` only to override it.
+    # Whether the final part waits for the decision was chosen when the upload started; pass `wait:`
+    # only to override it.
     # @option options [String] :asset_id
     # @option options [Hash] :part `{data:, part_number:, is_final:}`; part numbers start at 2.
-    # @option options [Boolean] :queue
+    # @option options [Boolean] :wait `true` to wait for the decision, `false` to return with the
+    #   asset `queued`
     # @return [Hash] the asset; `classification.status` stays `uploading` until the final part.
     def upload_part(options)
       call(options, __method__) do |api, request|
@@ -326,7 +346,7 @@ module CalmLens
         end
 
         body = UploadBody.from(part, multipart: true, part_size: !@session.defer_upload_checks)
-        send_part(api['assetId'], number, part.fetch('isFinal', false), body, api.fetch('queue', nil), request)
+        send_part(api['assetId'], number, part.fetch('isFinal', false), body, api.fetch('wait', nil), request)
       end
     end
 
@@ -342,12 +362,12 @@ module CalmLens
         asset = retrieve('assetId' => asset_id, 'request_options' => request_options)
         processing = asset.dig('classification', 'status')
         moderation = asset.dig('classification', 'moderation', 'status')
-        return asset if moderation != PENDING_MODERATION_STATUS || FINISHED_PROCESSING_STATUSES.include?(processing)
+        return asset if SETTLED_STATUSES.include?(processing)
 
         remaining = deadline - @session.monotonic
         unless remaining.positive?
           raise TimeoutError.new(SdkErrorCodes::TIMEOUT,
-                                 "Asset #{asset['id']} had no moderation decision after #{timeout}s " \
+                                 "Asset #{asset['id']} was not settled after #{timeout}s " \
                                  "(processing #{processing}, moderation #{moderation})",
                                  details: { 'assetId' => asset['id'], 'classificationStatus' => processing,
                                             'moderationStatus' => moderation })
@@ -358,7 +378,7 @@ module CalmLens
       end
     end
 
-    def submit(options, request_options, queue)
+    def submit(options, request_options, wait)
       raise Internal.invalid('Asset name is required', ErrorCodes::INVALID_UPLOAD_PAYLOAD) if options['name'].to_s.empty?
       unless %w[content part url].one? { |key| options.key?(key) } && !options.key?('isFinal')
         raise Internal.invalid('Supply exactly one of content, part, or url; isFinal belongs in part',
@@ -366,7 +386,7 @@ module CalmLens
       end
       options = with_used_context(options)
       if options.key?('url')
-        return expect_asset(request('POST', project('assets'), query: { 'queue' => queue }, body: options,
+        return expect_asset(request('POST', project('assets'), query: { 'wait' => wait }, body: options,
                                                                idempotent: true, request_options: request_options))
       end
 
@@ -380,16 +400,40 @@ 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)
+      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
+      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
 
-      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
+    # 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.
@@ -400,14 +444,14 @@ module CalmLens
     # 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)
+    def upload_in_parts(options, request_options, wait, 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)
+        mime.start_with?('image/') ? check_image_size(body.size) : check_upload_size(mime, body.size, in_parts: true)
       end
 
       total = body.size
@@ -416,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('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' }))
+      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
 
@@ -452,16 +493,16 @@ module CalmLens
       asset
     end
 
-    def send_part(asset_id, number, final, body, queue, request_options)
+    def send_part(asset_id, number, final, body, wait, request_options)
       query = { 'partNumber' => number, 'isFinal' => final, 'sizeInBytes' => body.size }
-      query['queue'] = queue unless queue.nil?
+      query['wait'] = wait unless wait.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.
+    # 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')
 
@@ -471,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?)
@@ -479,7 +521,10 @@ module CalmLens
       end
 
       final = content.fetch('isFinal', false)
-      check_image_size(total || body.size) if mime.start_with?('image/') && !@session.defer_upload_checks
+      unless @session.defer_upload_checks
+        # A declared whole-file size over the limit for parts can never finish.
+        mime.start_with?('image/') ? check_image_size(total || body.size) : check_upload_size(mime, total, in_parts: true)
+      end
       { 'partNumber' => 1, 'isFinal' => final, 'totalSizeInBytes' => total }
     end
 
@@ -495,45 +540,34 @@ module CalmLens
       raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Expected an asset response', status: 200)
     end
 
-    def check_signed_url(body)
-      resource = body.fetch('resource', 'rendered')
-      raise Internal.invalid("A signed URL's resource must be original or rendered") unless %w[original rendered].include?(resource)
-      if resource == 'original' && (body.key?('lens') || body.key?('transform'))
-        raise Internal.invalid('Lenses and transforms apply only to the rendered resource')
-      end
-
-      expires = body['expiresInSeconds']
-      return if expires.is_a?(Integer) && expires.between?(1, MAX_SIGNED_URL_SECONDS)
-
-      raise Internal.invalid('expires_in_seconds must be a whole number from 1 to 86400')
-    end
-
     def check_mime(type)
       mime = type.to_s.split(';').first.to_s.strip.downcase
       unless Internal.accepted_upload_mime_type?(mime)
-        raise InvalidArgumentError.new(ErrorCodes::INVALID_UPLOAD_MIME_TYPE,
+        raise InvalidArgumentError.new(ErrorCodes::UNSUPPORTED_UPLOAD_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 })
+                                       'application/pdf, or text/plain.', details: { 'mimeType' => type, 'source' => 'calmlens' })
       end
       raise Internal.invalid('Content type cannot contain line breaks') unless type.match?(Internal::HEADER_VALUE)
 
       mime
     end
 
-    # 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)
+    # Refuses content whose known size is over the API's limit for its type, before any of it is
+    # sent: `in_parts` selects the limits for content sent in parts. Images in parts are checked by
+    # {#check_image_size}.
+    def check_upload_size(mime, size, in_parts: false)
       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']
+                         [in_parts ? MAX_LONG_MEDIA_BYTES : MAX_MEDIA_BYTES,
+                          'Audio and video files can be at most 50 MiB in one request, or 2 GiB in parts']
                        else
                          [MAX_FILE_BYTES, 'Files can be at most 5,000 MiB']
                        end
-      raise Internal.invalid(message, ErrorCodes::FILE_TOO_LARGE) if size > limit
+      raise too_large(message, limit) if size > limit
     end
 
     # Images in parts total at most 20 MiB, at any size below that; a declared total is checked
@@ -541,7 +575,12 @@ module CalmLens
     def check_image_size(size)
       return unless size > MAX_MULTIPART_IMAGE_BYTES
 
-      raise Internal.invalid('Multipart image uploads cannot exceed 20MB.', ErrorCodes::MULTIPART_IMAGE_TOO_LARGE)
+      raise too_large('Multipart image uploads cannot exceed 20 MiB.', MAX_MULTIPART_IMAGE_BYTES)
+    end
+
+    # `upload/too-large` for content over the plan's `limit` bytes, as the API answers it.
+    def too_large(message, limit)
+      InvalidArgumentError.new(ErrorCodes::UPLOAD_TOO_LARGE, message, details: { 'limitBytes' => limit, 'source' => 'plan' })
     end
   end
 end