calmlens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86b8ba4a942285cf19fd32a128390b7dc9c19c8317b3e6d6b3d03d42306d7811
+  data.tar.gz: fad92edc638c5a38cc99a60687251c7c20b13f41899a8f123182d0ac341b1a8c
+SHA512:
+  metadata.gz: cd376e3647215281732a95ff55bd91b86155bad65782e632c264f5c0f43ceb61fa3b8db56346951c0dd4b98f214ebe309f0e70b447dc9ab6af237b2e91e6dcb1
+  data.tar.gz: a636fe02abe826b641223ef4d1c712a86942116ea13914af934bc8800b4b99ffde9ceae2501e58734e389b0bc09307aa468c7fedd0f6467cd542e4d23a7fd0f4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CalmLens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,222 @@
+# CalmLens Ruby SDK
+
+Ruby 3.1+ server-side client for CalmLens moderation, uploads, events, webhooks and CDN delivery. It uses only the standard library (Net::HTTP, JSON, OpenSSL). Calls accept keyword arguments in snake_case (or the API's camelCase); responses are Hashes with the API's camelCase string keys.
+
+```ruby
+require 'calmlens'
+client = CalmLens::ServerClient.new(api_key: ENV.fetch('CALMLENS_API_KEY'), project_id: ENV.fetch('CALMLENS_PROJECT_ID'))
+result = client.assets.moderate(name: 'text', content: {plain_text: 'Hello world', type: 'text/plain'})
+asset = client.assets.create(name: 'note.txt', content: {data: 'Hello', type: 'text/plain'})
+client.close
+```
+
+Install from RubyGems: `gem install calmlens`, or add `gem "calmlens"` to your Gemfile. The gem has no runtime dependencies and ships YARD documentation and RBS signatures in `sig/` (see [Types](#types)).
+
+Resources cover every API operation: assets create/moderate/search/list/each/retrieve/wait_for_decision/update/retry/delete_content/delete/move/list_children/each_child/upload_part/create_signed_url; folders list/create/retrieve/update/move/delete; text moderation; events list/each/each_page; CDN URL building and serving; and `ensure_lens`/`ensure_lenses`. `CalmLens::VERSION` holds the gem version.
+
+## Options
+
+Every option name may be snake_case or camelCase, at any depth, so options added to the API later work without an SDK update (`processing_options: {features: {face_detection: {enabled: true, age_estimation: true}}}` is sent as `processingOptions.features.faceDetection.ageEstimation`). Keys inside `metadata` are yours and are sent unchanged.
+
+Any method also accepts `request_options:`:
+
+| Key | Meaning |
+|---|---|
+| `idempotency_key` | The `Idempotency-Key` for an upload. The SDK generates one when you omit it. |
+| `timeout` | Seconds allowed for each socket read or write for this call. |
+| `open_timeout` | Seconds allowed to open a connection for this call. |
+| `max_retries` | Retries for this call (see below). |
+
+## Types
+
+`sig/` holds RBS signatures for every public method, with record types for each option Hash and response (in `sig/types.rbs`): `CalmLens::asset` (with `asset_processing`, `asset_moderation` and `asset_content`), `classification_report` (categories, qualifiers, labels, media segments and `features` results), `processing_options_input`, `folder`, `lens`, `event`, `events_page`, `asset_page`, `asset_search_response`, `signed_url`, `webhook_event_data` and the rest. Steep and other RBS tools check your calls and the response keys you read:
+
+```ruby
+asset = client.text.moderate(text: 'Hello', processing_options: { features: { face_detection: { enabled: true } } })
+asset['moderation']['status']                                              # CalmLens::asset_moderation_status
+asset.dig('moderation', 'report', 'features', 'faceDetection', 'faces')    # Array[CalmLens::detected_face]?
+```
+
+The signatures describe snake_case Symbol option keys; camelCase and String keys still work at runtime but are not typed. Results whose fields depend on `status` (category, qualifier and feature results) are typed as one record with those fields optional: check `status`, then read `score` or `reason`. `metadata` values and API error `details` are any JSON (`CalmLens::json_value`).
+
+## Moderation results
+
+`assets.moderate` and `text.moderate` return the asset, whose state is in three parts:
+
+- `processing`: `status` is `uploading`, `processing`, `done` or `failed` (retry with `assets.retry`), with `updatedAt` and, during a multipart upload, `uploadPartsReceived`.
+- `moderation`: `status` is the decision in force, `pending`, `approved` or `rejected` (a reviewer's decision wins over the automated one). `action` is what your policy did with flagged content (`alert`, `hide` or `purge`), or nil when nothing was flagged; it stays after a reviewer decides. `note` explains an automated rejection; `reviewerAction`, `reviewerNote`, `reviewerUserId` and `reviewedAt` describe a review; `decidedAt` is when the decision in force was made; `report` is the moderation report.
+- `content`: `status` is `temporary` (held until processing finishes), `stored` (kept with `keep_content_after_processing: true`) or `removed`, with `removalReason` (`policy`, `retention`, `requested`, `parent-removed` or `disposed`). It also holds `format` (MIME type), `extension`, `sizeInBytes`, `checksums`, `image`, `previewImage`, `extractedText` and `safetyHold`.
+
+Publish only when `asset['moderation']['status']` is `approved` and `asset['moderation']['action']` is nil. New statuses, visibilities and fields may appear in later API versions: the SDK returns them unchanged, so treat any value you do not recognise as not ready.
+
+### Waiting for a decision
+
+`assets.wait_for_decision` waits for a queued asset's decision and returns the asset once `moderation.status` is `approved` or `rejected`, or `processing.status` is `failed`. It retrieves the asset every few seconds and raises `CalmLens::TimeoutError` with code `sdk/timeout` if there's no decision within `timeout:` seconds (default 60); `details` holds `'assetId'` and the last `'processingStatus'` and `'moderationStatus'`. Use it after `assets.create`, or with an asset ID you stored earlier. Webhooks report decisions without polling.
+
+```ruby
+queued = client.assets.create(name: 'photo.jpg', content: {data: File.open('photo.jpg', 'rb'), type: 'image/jpeg'})
+decided = client.assets.wait_for_decision(asset_id: queued['id'], timeout: 30)
+hide_photo(decided['id']) if decided['moderation']['status'] == 'rejected'
+```
+
+`timeout:` covers the whole wait; `request_options: {timeout:}` still limits each request. The call only sleeps and sends requests, so you can stop it early by stopping its thread.
+
+## Uploads and delivery
+
+Content is `{type:, plain_text:}`, `{type:, base64:}` or `{type:, data:}`, where `data` is a binary String or an IO. An IO is streamed with a `Content-Length` and never read into memory; a File, Tempfile or StringIO knows its size, and other streams (pipes, sockets) need `size_in_bytes:`. A stream that ends early or holds more bytes than declared fails with `upload/invalid-payload`.
+
+```ruby
+File.open('video.mp4', 'rb') do |file|
+  client.assets.create(name: 'video.mp4', content: {data: file, type: 'video/mp4'})
+end
+```
+
+Multipart uploads start with `part:` on `create`/`moderate` and continue with `upload_part`. The queue mode chosen at the start is saved with the upload, so later parts can come from another process; pass `queue:` to `upload_part` only to override it. Pass `total_size_in_bytes:` at the start when you know the file size. See [Multipart uploads](https://calmlens.com/docs/guides/multipart-uploads).
+
+`cdn.serve` fetches content with the API key. With a block it yields a `CalmLens::Response` whose body streams; without one it returns the response with the body read. Error statuses are returned, not raised.
+
+```ruby
+File.open('photo.jpg', 'wb') do |file|
+  client.cdn.serve(asset_identifier: asset_id) do |response|
+    raise "CDN returned #{response.status}" unless response.success?
+    response.each_chunk { |chunk| file.write(chunk) }
+  end
+end
+```
+
+Use `create_signed_url` to deliver private content to browsers without your key.
+
+`cdn.get_asset_url`, `cdn.serve` and `create_signed_url` accept a `lens:`, a `transform:`, or both (the lens runs first). A transform is a selector string or structured steps (one Hash or an Array), serialized with sorted option keys:
+
+```ruby
+client.cdn.get_asset_url(asset_identifier: asset_id, transform: 'imageTransform[format=png,width=1024]')
+client.cdn.get_asset_url(asset_identifier: asset_id, transform: {type: 'imageTransform', options: {width: 1024, format: 'png'}})
+# => ".../content/imageTransform[format=png,width=1024]" in both cases
+```
+
+## Upload presets
+
+Pass `upload_preset_id:` to `assets.create` or `assets.moderate` to apply an upload preset's folder, visibility, file types and size limit. To let a browser upload through a preset that requires tokens, sign a single-use token on your server. Signing happens locally with your API key and makes no request.
+
+```ruby
+signed = client.upload_tokens.sign(
+  upload_preset_id: 'your-upload-preset-id',
+  external_id: 'post-42',     # optional: the uploaded asset gets this ID
+  expires_in_seconds: 600     # optional: 1 to 3600, 600 by default
+)
+# signed['token'], signed['expiresAt'] (milliseconds since the Unix epoch)
+```
+
+See [Upload presets](https://calmlens.com/docs/guides/upload-presets). `CalmLens::MockServerClient` signs tokens with its own key.
+
+## Pagination
+
+`assets.each`, `assets.each_child`, `events.each` and `events.each_page` fetch pages as you iterate and return an Enumerator without a block, so `client.assets.each(filter: 'moderation.status==approved').lazy.first(5)` stops after the pages it needs.
+
+## Events feed
+
+`events.list` without `after` returns **no events** and a cursor for the current time. Store it, then read on from it; persist each page's cursor once its events are handled.
+
+```ruby
+cursor = client.events.list['cursor'] # start from now
+# ...later, and on every poll:
+client.events.each_page(after: cursor, limit: 50) do |page|
+  page['events'].each { |event| handle(event) } # event['type'], event['facts'], event['assetId']
+  cursor = page['cursor'] # persist it
+end
+```
+
+Each event carries `facts`, an array of `{'key', 'value', 'url'?}` entries registered for its `type`. An unknown cursor raises `events/invalid-cursor`.
+
+## Webhooks
+
+Verify the **raw** request body, never re-serialized JSON. `CalmLens.parse_webhook_event` verifies the signature and timestamp, then parses the delivery into a `CalmLens::WebhookEvent` (`id`, `type`, `created_at`, `project_id`, `data`, plus `asset_id`, `facts` and `test?`). It raises `CalmLens::WebhookVerificationError` with code `sdk/invalid-webhook-signature` or `sdk/invalid-webhook-payload`. Passing a parsed Hash instead of the body raises `CalmLens::InvalidArgumentError`.
+
+Rails:
+
+```ruby
+class CalmLensWebhooksController < ActionController::API
+  def create
+    event = CalmLens.parse_webhook_event(
+      payload: request.raw_post,
+      signature: request.headers[CalmLens::WEBHOOK_SIGNATURE_HEADER],
+      timestamp: request.headers[CalmLens::WEBHOOK_TIMESTAMP_HEADER],
+      secret: ENV.fetch('CALMLENS_WEBHOOK_SECRET')
+    )
+    # Acknowledge first; do the work in a job. Skip a delivery ID you have already queued.
+    CalmLensEventJob.perform_later(request.headers[CalmLens::WEBHOOK_DELIVERY_HEADER], event.to_h)
+    head :no_content
+  rescue CalmLens::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+Sinatra (or any Rack app):
+
+```ruby
+post '/webhooks/calmlens' do
+  request.body.rewind
+  event = CalmLens.parse_webhook_event(
+    payload: request.body.read,
+    signature: request.env['HTTP_X_CALMLENS_SIGNATURE'],
+    timestamp: request.env['HTTP_X_CALMLENS_TIMESTAMP'],
+    secret: ENV.fetch('CALMLENS_WEBHOOK_SECRET')
+  )
+  enqueue(request.env['HTTP_X_CALMLENS_DELIVERY'], event)
+  204
+rescue CalmLens::WebhookVerificationError
+  400
+end
+```
+
+The header names are exported as `CalmLens::WEBHOOK_SIGNATURE_HEADER`, `WEBHOOK_TIMESTAMP_HEADER` and `WEBHOOK_DELIVERY_HEADER`. Retries of one delivery repeat its `x-calmlens-delivery` ID, so use it to skip duplicates. Deliveries signed more than `CalmLens::WEBHOOK_SIGNATURE_TOLERANCE_SECONDS` (300) from your clock fail; change it with `tolerance_seconds:`. `CalmLens.verify_webhook_signature` returns true or false instead of raising, and `CalmLens.create_webhook_signature_header(payload:, timestamp:, secret:)` signs a body, for example to test your receiver.
+
+## Errors
+
+Every error the SDK raises is a `CalmLens::Error` with `code`, `message`, `details`, `status` (nil without a response), `request_id` (the `X-Request-Id` header, for support), `headers`, `retry_after` (seconds from `Retry-After`) and the original exception in `cause`. Helpers: `not_found?` and `retryable?`. Compare codes with the constants in `CalmLens::ErrorCodes` (API codes, generated from the API's list, with their HTTP statuses in `ErrorCodes::STATUSES`) and `CalmLens::SdkErrorCodes`.
+
+| Class | When |
+|---|---|
+| `CalmLens::APIError` and its subclasses `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServerError` | The API answered with an error status. |
+| `CalmLens::ConnectionError` (`sdk/transport-error`), `CalmLens::TimeoutError` (`sdk/timeout`) | No complete response arrived, or `assets.wait_for_decision` had no decision in time. |
+| `CalmLens::InvalidResponseError` (`sdk/invalid-response`, `sdk/response-too-large`) | A successful response could not be read, or was larger than 32 MiB. |
+| `CalmLens::InvalidArgumentError` (`sdk/invalid-argument`, or an `upload/*` code for payload checks the API also makes) | An argument was rejected before sending. |
+| `CalmLens::ConfigurationError` (`sdk/invalid-config`) | `ServerClient.new` received an invalid setting, such as a malformed `base_url`. |
+| `CalmLens::WebhookVerificationError` | A webhook delivery failed verification. |
+
+## Retries and timeouts
+
+Requests that are safe to repeat are retried up to `max_retries:` times (default 2): GET and HEAD, and uploads, which carry an `Idempotency-Key` reused on every retry so CalmLens runs them once and replays the saved response. Connection failures, timeouts, `429`, `502`, `503`, `504` and `idempotency/request-in-progress` are retried with jittered exponential backoff (`retry_base_delay:`, default 0.5 seconds, at most 8), waiting for `Retry-After` when the API sends one. Other writes are never retried. A streamed upload is retried only when its IO can seek back.
+
+`timeout:` (default 120 seconds) limits each socket read or write, not a whole transfer, so large uploads and downloads are not cut off. `open_timeout:` (default 10 seconds) limits connecting. Both can be set per call with `request_options:`.
+
+## Connections
+
+Reuse one client: it keeps up to 8 idle keep-alive connections per host, is safe to share between threads, never follows redirects, and after `fork` (Puma, Unicorn, Resque) the child opens its own connections instead of sharing the parent's. Call `close` when finished. Requests identify themselves as `calmlens-ruby/<version> (ruby <version>)`. `inspect` never shows the API key.
+
+## Offline testing
+
+```ruby
+require 'calmlens/testing'
+mock = CalmLens::MockServerClient.new
+asset = mock.assets.moderate(name: 'note', content: {plain_text: 'hello', type: 'text/plain'},
+                             processing_options: {keep_content_after_processing: true})
+mock.assets.retrieve(asset_id: asset['id']).dig('moderation', 'status') # => "approved"
+mock.assets.list(filter: 'moderation.status==approved')['items'].length        # => 1
+mock.cdn.serve(asset_identifier: asset['id']).body                      # => "hello"
+
+mock.enqueue(status: 503, body: {code: 'server/unavailable', message: 'Busy'}) # answers the next request
+mock.enqueue_error(Net::ReadTimeout.new)            # the next request raises CalmLens::TimeoutError
+mock.enqueue_event(type: 'asset.approved', asset_id: asset['id']) # joins the events feed
+
+request = mock.requests.last
+request.method # => "GET"
+request.path   # => "/assets/project-1/<id>/content" (relative to base_url or cdn_base_url)
+```
+
+`MockServerClient` runs the real client's validation, encoding, retries and error handling, then answers from an in-memory stand-in for the API and CDN. Uploads create assets you can retrieve, list, search, move and delete, and `assets.wait_for_decision` checks the stored asset's processing and moderation status; folders, multipart uploads, idempotency keys, lenses and the events feed behave like the API's; errors carry the API's codes, HTTP statuses and body shape; and `cdn.serve` returns stored bytes with real headers. Like the API, content is removed (`removalReason` `retention`) once processing is `done` unless the upload sets `keep_content_after_processing: true`. List filters support `==` and `!=` (with `*` wildcards) joined by `;` and `,`, on top-level and nested names such as `moderation.status`, `processing.status`, `content.status` and `content.format`; other RSQL operators raise rather than being ignored. It does not classify content: `moderate` gives `analyzed_outcome:` and `create` gives `queued_outcome:`. An outcome is `pending` (still processing), `approved` or `rejected` (processing done with that decision) or `failed` (processing failed, retryable). `analyzed_outcome:` can also be fields to deep-merge into the asset, such as `{'moderation' => {'status' => 'rejected', 'action' => 'hide'}}` (the outcome follows `moderation.status`), or a callable that receives the asset and returns either. Change records through `mock.state` to arrange a test. Queued responses and errors are used first, in order.
+
+## Development
+
+Native tests (Ruby 3.1+, Bundler 2.6+): `bundle install && bundle exec ruby -Ilib -e 'Dir["test/*_test.rb"].each { |file| require_relative file }'`, and lint with `bundle exec rubocop`. `lib/calmlens/error_codes.rb` and the files in `testdata/` are generated by `bun packages/sdk-contract/generate.ts` from the repository root. Container/backend checks: `bun run test:sdk:e2e`. Type-check the signatures with `gem install steep && steep check` (see `Steepfile`) and `rbs -I sig validate`. Release by setting `CalmLens::VERSION` in `lib/calmlens/version.rb`.

data/lib/calmlens/assets.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # Uploads, moderation and management of assets. Reach it through {ServerClient#assets}.
+  #
+  # Every method takes an options Hash (or keyword arguments) whose names may be snake_case
+  # (`asset_id:`) or the API's camelCase (`'assetId'`); keys inside `metadata` are sent unchanged.
+  # Any method also accepts `request_options: { idempotency_key:, timeout:, open_timeout:, max_retries: }`.
+  # Results are Hashes with the API's camelCase string keys. Fields and enum values added to the API
+  # later appear as they are, so compare `moderation.status` and similar values with known strings
+  # and treat anything else as not ready.
+  class Assets < Resource
+    SUBMIT_QUERY_KEYS = %w[name description processingOptions visibility metadata externalId externalUrl
+                           folderId uploadPresetId].freeze
+    MIN_MULTIPART_IMAGE_BYTES = 10 * 1024 * 1024
+    MAX_MULTIPART_IMAGE_BYTES = 20 * 1024 * 1024
+    # Moderation statuses that carry a decision; {#wait_for_decision} returns once an asset has one,
+    # or once its processing status is in {FINISHED_PROCESSING_STATUSES}.
+    DECIDED_MODERATION_STATUSES = %w[approved rejected].freeze
+    # Processing statuses after which no decision will arrive without a retry.
+    FINISHED_PROCESSING_STATUSES = %w[failed].freeze
+    DECISION_POLL_FIRST_DELAY = 0.5
+    DECISION_POLL_MAX_DELAY = 5.0
+    DEFAULT_DECISION_TIMEOUT = 60
+
+    # Searches assets by meaning or keyword.
+    # @option options [String] :query
+    # @option options [String] :mode `hybrid`, `semantic` or `keyword`
+    # @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) }
+    end
+
+    # Lists one page of assets.
+    # @option options [String] :cursor from the previous page
+    # @option options [Integer] :page_size
+    # @option options [String] :filter an RSQL filter such as `moderation.status==approved`
+    # @option options [Array<Hash>] :ordering `[{field: 'createdAt', direction: 'DESC'}]`
+    # @return [Hash] `{'items', 'total', 'hasMore', 'cursor', 'pageSize'}`
+    def list(options = {})
+      call(options) do |api, request|
+        request('GET', project('assets/page'), query: api, request_options: request)
+      end
+    end
+
+    # Iterates every asset matching the options, fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam asset [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      api, request = call(options) { |*split| split }
+      listing = pages(api['cursor']) { |index| list(api.merge('cursor' => index, 'request_options' => request)) }
+      listing.each { |page| page['items'].each(&block) }
+      nil
+    end
+
+    # Lists one page of an asset's children, such as frames extracted from a video.
+    # @option options [String] :asset_id
+    # @return [Hash] a page like {#list}
+    def list_children(options)
+      call(options) do |api, request|
+        query = without(api, 'assetId')
+        request('GET', "/assets/#{Internal.segment(api['assetId'])}/children", query: query, request_options: request)
+      end
+    end
+
+    # Iterates every child of an asset, fetching pages as needed.
+    # @param options [Hash] the options of {#list_children}
+    # @yieldparam asset [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each_child(options, &block)
+      return enum_for(:each_child, options) unless block
+
+      api, request = call(options) { |*split| split }
+      listing = pages(api['cursor']) { |index| list_children(api.merge('cursor' => index, 'request_options' => request)) }
+      listing.each { |page| page['items'].each(&block) }
+      nil
+    end
+
+    # @option options [String] :asset_id
+    # @return [Hash] the asset
+    def retrieve(options)
+      call(options) do |api, request|
+        request('GET', "/assets/#{Internal.segment(api['assetId'])}", request_options: request)
+      end
+    end
+
+    # Waits until an asset's `moderation.status` is `approved` or `rejected`, or its
+    # `processing.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.
+    # 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
+    #   `'assetId'` and the last `'processingStatus'` and `'moderationStatus'`.
+    def wait_for_decision(options)
+      call(options) 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')
+        end
+
+        poll_for_decision(api['assetId'], request, timeout)
+      end
+    end
+
+    # Updates an asset's name, description, tags, visibility, metadata and similar fields.
+    # @option options [String] :asset_id
+    # @return [Hash] the updated asset
+    def update(options)
+      call(options) do |api, request|
+        request('PATCH', "/assets/#{Internal.segment(api['assetId'])}", body: without(api, 'assetId'),
+                                                                        request_options: request)
+      end
+    end
+
+    # Processes an asset whose `processing.status` is `failed` again.
+    # @option options [String] :asset_id
+    # @return [Hash] the asset
+    def retry(options)
+      call(options) do |api, request|
+        request('POST', "/assets/#{Internal.segment(api['assetId'])}/retry", request_options: request)
+      end
+    end
+
+    # Removes the stored content and returns the asset with `content.status` `removed` (reason
+    # `requested`); the record and moderation report are kept.
+    # @option options [String] :asset_id
+    # @return [Hash] the asset
+    def delete_content(options)
+      call(options) do |api, request|
+        request('DELETE', "/assets/#{Internal.segment(api['assetId'])}/content", request_options: request)
+      end
+    end
+
+    # Deletes the asset record and its stored content.
+    # @option options [String] :asset_id
+    # @return [nil]
+    def delete(options)
+      call(options) do |api, request|
+        request('DELETE', "/assets/#{Internal.segment(api['assetId'])}", request_options: request)
+        nil
+      end
+    end
+
+    # Moves an asset into a folder, or to the project root with `folder_id: nil`.
+    # @option options [String] :asset_id
+    # @option options [String, nil] :folder_id
+    # @return [Hash] the asset
+    def move(options)
+      call(options) do |api, request|
+        request('POST', "/assets/#{Internal.segment(api['assetId'])}/move",
+                body: { 'folderId' => Internal.required(api, 'folderId') }, request_options: request)
+      end
+    end
+
+    # Creates a time-limited URL that delivers private content without an API key.
+    # @option options [String] :asset_id
+    # @option options [String] :resource `content` (default) or `preview`
+    # @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
+    # @return [Hash] `{'url', 'expiresAt'}`
+    def create_signed_url(options)
+      call(options) do |api, request|
+        body = without(api, 'assetId')
+        body['transform'] = Transforms.selector(body['transform']) if body.key?('transform')
+        request('POST', "/assets/#{Internal.segment(api['assetId'])}/signed-url",
+                body: { 'resource' => 'content', 'expiresInSeconds' => 900 }.merge(body),
+                request_options: request)
+      end
+    end
+
+    # Uploads content and queues moderation; the call returns before classification finishes.
+    # Watch for `asset.approved` and `asset.rejected` events or retrieve the asset later.
+    #
+    # Give exactly one of `content:` (a whole file), `part:` (the first part of a multipart upload) or
+    # `url:` (a web page or file to fetch). Content is `{type:, plain_text:}`, `{type:, base64:}` or
+    # `{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).
+    #
+    # The request carries an `Idempotency-Key` (generated unless you pass
+    # `request_options: {idempotency_key:}`), so a retried upload never creates a second asset.
+    # @option options [String] :name
+    # @option options [Hash] :content
+    # @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
+    # @return [Hash] the asset
+    def create(options)
+      call(options) { |api, request| submit(api, request, true) }
+    end
+
+    # Uploads content and waits for the moderation decision where the content type supports it.
+    # Audio and video are always processed asynchronously. Takes the options of {#create}.
+    # @return [Hash] the asset; publish only when `moderation.status` is `approved` and
+    #   `moderation.action` is nil.
+    def moderate(options)
+      call(options) 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 moderate must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+        end
+
+        submit(api, request, false)
+      end
+    end
+
+    # Uploads a later part of a multipart upload started with {#create} or {#moderate} and `part:`.
+    # The queue mode chosen at the start applies; pass `queue:` 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
+    # @return [Hash] the asset; `processing.status` stays `uploading` until the final part.
+    def upload_part(options)
+      call(options) do |api, request|
+        path = "/assets/#{Internal.segment(api['assetId'])}/part"
+        part = api['part']
+        raise Internal.invalid('part is required') unless part.is_a?(Hash)
+
+        number = part['partNumber']
+        unless number.is_a?(Integer) && number.positive?
+          raise Internal.invalid('partNumber must be a positive Integer',
+                                 ErrorCodes::INVALID_UPLOAD_PART_NUMBER)
+        end
+
+        body = UploadBody.from(part, multipart: true)
+        query = { 'partNumber' => number, 'isFinal' => part.fetch('isFinal', false), 'sizeInBytes' => body.size }
+        query['queue'] = api['queue'] if api.key?('queue')
+        request('POST', path, query: query, raw: body, idempotent: true, request_options: request,
+                              headers: { 'Content-Type' => 'application/octet-stream', 'X-CalmLens-Upload' => 'part' })
+      end
+    end
+
+    private
+
+    def poll_for_decision(asset_id, request_options, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      delay = DECISION_POLL_FIRST_DELAY
+      loop do
+        asset = retrieve('assetId' => asset_id, 'request_options' => request_options)
+        processing = asset.dig('processing', 'status')
+        moderation = asset.dig('moderation', 'status')
+        return asset if DECIDED_MODERATION_STATUSES.include?(moderation) || FINISHED_PROCESSING_STATUSES.include?(processing)
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        unless remaining.positive?
+          raise TimeoutError.new(SdkErrorCodes::TIMEOUT,
+                                 "Asset #{asset['id']} had no moderation decision after #{timeout}s " \
+                                 "(processing #{processing}, moderation #{moderation})",
+                                 details: { 'assetId' => asset['id'], 'processingStatus' => processing,
+                                            'moderationStatus' => moderation })
+        end
+
+        sleep([delay, remaining].min)
+        delay = [delay * 1.5, DECISION_POLL_MAX_DELAY].min
+      end
+    end
+
+    def submit(options, request_options, queue)
+      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',
+                               ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+      if options.key?('url')
+        return request('POST', project('assets'), query: { 'queue' => queue }, body: options, idempotent: true,
+                                                  request_options: request_options)
+      end
+
+      multipart = options.key?('part')
+      content = options.fetch(multipart ? 'part' : 'content')
+      raise Internal.invalid('Upload content must be a Hash', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless content.is_a?(Hash)
+
+      mime = check_mime(content['type'])
+      if multipart && content.fetch('partNumber', 1) != 1
+        raise Internal.invalid('Use uploadPart for multipart upload parts after the first part', ErrorCodes::USE_UPLOAD_PART)
+      end
+
+      body = UploadBody.from(content, multipart: multipart)
+      query = options.slice(*SUBMIT_QUERY_KEYS).merge('queue' => queue, 'contentType' => content['type'],
+                                                      'sizeInBytes' => body.size)
+      if multipart
+        total = options['totalSizeInBytes']
+        unless total.nil? || (total.is_a?(Integer) && total.positive?)
+          raise Internal.invalid('totalSizeInBytes must be a positive Integer', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+        end
+
+        check_image_size(total || body.size, total || content.fetch('isFinal', false)) if mime.start_with?('image/')
+        query.merge!('partNumber' => 1, 'isFinal' => content.fetch('isFinal', false), 'totalSizeInBytes' => total)
+      end
+      request('POST', project('assets'),
+              query: query, raw: body, idempotent: true, request_options: request_options,
+              headers: { 'Content-Type' => content['type'], 'X-CalmLens-Upload' => multipart ? 'part' : 'content' })
+    end
+
+    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)
+      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
+
+      raise Internal.invalid('Multipart image uploads must total at least 10MB.', ErrorCodes::MULTIPART_IMAGE_TOO_SMALL)
+    end
+  end
+end

data/lib/calmlens/cdn.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # CDN URLs and authenticated content delivery. Reach it through {ServerClient#cdn}.
+  class CDN < Resource
+    # Builds the CDN URL of an asset's content or preview. Private assets need the API key
+    # ({#serve}) or a signed URL ({Assets#create_signed_url}).
+    # @option options [String] :asset_identifier the asset ID or external ID
+    # @option options [String] :resource `content` (default) or `preview`
+    # @option options [String] :lens a lens identifier
+    # @option options [String, Hash, Array<Hash>] :transform a selector such as `imageTransform[width=200]`,
+    #   or structured steps: `{type: 'imageTransform', options: {width: 200}}` or an Array of them
+    # @return [String]
+    def get_asset_url(options)
+      call(options) { |api, _request| url(api) }
+    end
+
+    # Fetches content from the CDN with the client's API key.
+    #
+    # With a block, yields a {Response} whose body streams: call {Response#each_chunk} to write
+    # it somewhere without holding it in memory. The method returns the block's value. Without a
+    # block, returns the {Response} with its body read into memory. Error statuses are returned,
+    # not raised; check {Response#status}.
+    #
+    # @option options [String] :asset_identifier
+    # @option options [Hash] :init `{method: 'GET' | 'HEAD', headers: {...}}`
+    # @yieldparam response [Response]
+    # @return [Response, Object]
+    # @example Save content to a file
+    #   File.open('photo.jpg', 'wb') do |file|
+    #     client.cdn.serve(asset_identifier: id) do |response|
+    #       raise "CDN returned #{response.status}" unless response.success?
+    #       response.each_chunk { |chunk| file.write(chunk) }
+    #     end
+    #   end
+    def serve(options, &)
+      method, url, headers, request = call(options) do |api, request_options|
+        init = api.fetch('init', {})
+        raise Internal.invalid('init must be a Hash') unless init.is_a?(Hash)
+
+        verb = init.fetch('method', 'GET').to_s.upcase
+        raise Internal.invalid('init.method must be GET or HEAD') unless %w[GET HEAD].include?(verb)
+
+        [verb, url(api), Internal.headers(init.fetch('headers', {})), request_options]
+      end
+      @session.cdn(method, url, headers, request, &)
+    end
+
+    private
+
+    def url(api)
+      resource = api.fetch('resource', 'content')
+      raise Internal.invalid('Resource must be content or preview') unless %w[content preview].include?(resource)
+
+      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 += "#{api['lens'] ? ',' : '/'}#{Transforms.path(transform)}" unless transform.nil? || transform == ''
+      url
+    end
+  end
+end