calmlens 0.20.0 → 0.21.0

data/lib/calmlens/cdn.rb

@@ -1,33 +1,129 @@
 # frozen_string_literal: true
 
 module CalmLens
-  # CDN URLs and authenticated content delivery. Reach it through {ServerClient#cdn}.
+  # Asset URLs, signed asset URLs, asset info and authenticated content delivery. Reach it through
+  # {ServerClient#cdn}.
+  #
+  # Every asset has one URL, `{cdn_base_url}/assets/{project_id}/{asset}`, where `{asset}` is the asset
+  # ID or `ext:` and the URL-encoded external ID. Each resource is a path beneath it, such as
+  # `/rendered` or `/preview/@thumbnail,width=320`. A signed asset URL ({#sign_asset_url}) replaces
+  # `{asset}` with a grant, and the same resources are paths beneath it.
   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
+    # Where each resource is served beneath an asset URL. The adaptive stream is its HLS master
+    # playlist; its media playlists and segments are the other files beneath `hls/`.
+    RESOURCE_PATHS = {
+      'original' => 'original', 'rendered' => 'rendered', 'preview' => 'preview',
+      'hls' => 'hls/index.m3u8', 'embed' => 'embed', 'placeholder' => 'placeholder', 'info' => 'info'
+    }.freeze
+    private_constant :RESOURCE_PATHS
 
-    # Builds the CDN URL of an asset's rendered, original or placeholder resource. 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 `rendered` (default), `original` or `placeholder`. Only `rendered`
-    #   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.
+    # Every CDN resource beneath an asset URL, as {#get_asset_url} and {#sign_asset_url} accept them.
+    RESOURCES = RESOURCE_PATHS.keys.freeze
+
+    # A signed asset URL's lifetime in seconds when `expires_in` is omitted: 15 minutes.
+    DEFAULT_SIGNED_URL_EXPIRES_IN = 15 * 60
+    # The longest signed asset URL lifetime the API accepts, in seconds: 24 hours.
+    MAX_SIGNED_URL_EXPIRES_IN = 24 * 60 * 60
+
+    # The start of the asset segment of a URL that names the asset by its external ID.
+    EXTERNAL_ID_PREFIX = 'ext:'
+
+    # The ISO 3166-1 alpha-2 countries a viewer's `region` can be. EU is not a viewer country.
+    VIEWER_COUNTRIES = %w[
+      AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY
+      BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK
+      FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR
+      IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK
+      ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM
+      PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF
+      TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW
+    ].freeze
+
+    # Builds an asset's CDN URL without a request: the asset URL, which every resource is a path
+    # beneath, or a resource URL when `resource` is given, with its lens or transform and the viewer
+    # claims. Use it for public assets; private ones need {#sign_asset_url} (or the API key, through
+    # {#serve}).
+    # @option options [String] :asset_id the asset ID; give it or `external_id`, not both
+    # @option options [String] :external_id the external ID the asset was uploaded with, written as
+    #   `ext:` and the URL-encoded ID
+    # @option options [String] :project_id the asset's project; the client's by default
+    # @option options [String] :resource `rendered` (the displayable file: an image in the best format the
+    #   client accepts, a PDF, or browser-safe video or audio), `original` (the exact upload), `preview` (a
+    #   still image for the asset), `hls` (the HLS master playlist of audio or video, at `hls/index.m3u8`,
+    #   once `content.hls` is set), `embed` (an HTML page that shows the asset, a viewer for its type, for an
+    #   iframe), `placeholder` (a small blurred PNG that the CDN serves publicly for every asset whatever its
+    #   visibility or moderation status, without age confirmation) or `info` (the asset's display info, as
+    #   {#get_asset_info} reads it). Without it, the URL is the asset URL itself. Lenses and transforms
+    #   apply to `preview`, and to `rendered` when it is an image; the CDN refuses them on rendered PDFs,
+    #   video and audio with `transform/invalid`, and the SDK refuses them on the other resources and
+    #   without a resource.
     # @option options [String] :lens a lens identifier
     # @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. 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.
+    # @option options [Hash] :viewer_claims `{region:, age_confirmed:}`, sent as a JSON `viewerClaims` query
+    #   parameter, leaving out the defaults (no region, age not confirmed). `region` is an ISO 3166-1
+    #   alpha-2 country. The CDN serves an asset whose moderation status is `age-restricted` only with
+    #   `age_confirmed: true`, even with a signed URL or the API key. Set it only where your app has
+    #   already decided the viewer may see age-restricted content. Your platform confirms the viewer's
+    #   age; CalmLens does not verify this claim, and anyone can add it to a URL.
     # @return [String]
     def get_asset_url(options)
-      call(options, __method__) { |api, _request| url(api) }
+      call(options, __method__) { |api, _request| asset_url(api) }
+    end
+
+    # Signs a private asset's URL on your server, so browsers and apps can load it without an API key
+    # until it expires. Every resource is a path beneath it, as beneath a public asset URL; `original`
+    # only when signed with `original: true`. With `resource`, returns that resource's URL beneath the
+    # grant; lenses, transforms and viewer claims are appended as {#get_asset_url} appends them and
+    # aren't part of the signature.
+    # @option options [String] :asset_id give it or `external_id`, not both
+    # @option options [String] :external_id
+    # @option options [String] :project_id the client's by default
+    # @option options [Integer] :expires_in whole seconds from 1 to 86400; 900 by default
+    # @option options [Boolean] :original whether the URL also serves the exact upload (`original`); false by default
+    # @option options [String] :resource see {#get_asset_url}
+    # @option options [String] :lens
+    # @option options [String, Hash] :transform
+    # @option options [Hash] :viewer_claims
+    # @return [Hash] `{'url', 'expiresAt'}`, `expiresAt` in milliseconds since the Unix epoch
+    def sign_asset_url(options)
+      call(options, __method__) do |api, request|
+        check_signing(api)
+        project = Internal.segment(api.fetch('projectId', @session.project_id))
+        body = api.slice('assetId', 'externalId')
+        body['expiresIn'] = api.fetch('expiresIn', DEFAULT_SIGNED_URL_EXPIRES_IN)
+        body['original'] = api.fetch('original', false)
+        signed = request('POST', "/projects/#{project}/signed-asset-urls", body: body, request_options: request)
+        unless signed.is_a?(Hash) && signed['url'].is_a?(String) && !signed['url'].empty? && signed['expiresAt'].is_a?(Integer)
+          raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'The API returned no signed asset URL')
+        end
+
+        { 'url' => append_location(signed['url'], api), 'expiresAt' => signed['expiresAt'] }
+      end
+    end
+
+    # Reads the display info of an asset URL, public or signed: `{url}/info`, with the asset's type,
+    # size, rendered file, preview and stream, and whether the viewer its claims describe can see it
+    # now (`availability`: `available`, `age-restricted` or `unavailable`). It sends no API key, as a
+    # browser would, so a private asset's info needs a signed URL.
+    # @param url [String] an asset URL from {#get_asset_url} or {#sign_asset_url}, without a resource
+    # @param viewer_claims [Hash, nil] the viewer's claims, as for {#get_asset_url}; the URL's own
+    #   `viewerClaims` when omitted
+    # @return [Hash] the asset info
+    # @raise [APIError] with the CDN's code, such as `signed-url/expired` or `asset/not-available`
+    def get_asset_info(url, viewer_claims: nil)
+      base, claims = split_asset_url(url)
+      claims = Internal.normalize(viewer_claims) unless viewer_claims.nil?
+      info = @session.cdn_json("#{base}/info#{viewer_claims_query(claims)}")
+      return info if asset_info?(info)
+
+      raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'The CDN returned no asset info')
+    rescue TypeError, ArgumentError, JSON::GeneratorError, EncodingError, URI::Error => e
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT, e.message), cause: e
     end
 
     # Fetches content from the CDN with the client's API key.
@@ -37,14 +133,19 @@ module CalmLens
     # 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 [String] :asset_id see {#get_asset_url}
+    # @option options [String] :external_id
+    # @option options [String] :project_id
+    # @option options [String] :resource `rendered` by default
+    # @option options [String] :lens
+    # @option options [String, Hash] :transform
     # @option options [Hash] :viewer_claims see {#get_asset_url}
     # @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|
+    #     client.cdn.serve(asset_id: id) do |response|
     #       raise "CDN returned #{response.status}" unless response.success?
     #       response.each_chunk { |chunk| file.write(chunk) }
     #     end
@@ -57,42 +158,97 @@ module CalmLens
         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]
+        [verb, asset_url({ 'resource' => 'rendered' }.merge(api)), Internal.headers(init.fetch('headers', {})), request_options]
       end
       @session.cdn(method, url, headers, request, &)
     end
 
     private
 
-    def url(api)
-      resource = api.fetch('resource', 'rendered')
-      raise Internal.invalid('Resource must be original, rendered or placeholder') unless RESOURCES.include?(resource)
+    def asset_url(api)
+      project = Internal.segment(api.fetch('projectId', @session.project_id))
+      append_location("#{@session.cdn_base_url}/assets/#{project}/#{asset_segment(api)}", api)
+    end
+
+    # The asset segment of a URL: the asset ID, or `ext:` and the URL-encoded external ID.
+    def asset_segment(api)
+      raise Internal.invalid('Pass either asset_id or external_id') if api.key?('assetId') == api.key?('externalId')
+      return Internal.segment(api['assetId']) if api.key?('assetId')
 
-      transformed = !api['lens'].nil? || !api['transform'].nil?
-      raise Internal.invalid('Lenses and transforms apply only to the rendered resource') if resource == 'original' && transformed
-      raise Internal.invalid('A placeholder takes no lens or transform') if resource == 'placeholder' && transformed
+      external = api['externalId']
+      raise Internal.invalid('external_id must be a non-empty String') unless external.is_a?(String) && !external.empty?
 
-      url = "#{@session.cdn_base_url}/assets/#{Internal.segment(@session.project_id)}/" \
-            "#{Internal.segment(api['assetIdentifier'])}/#{resource}"
-      transform = api['transform']
-      selector = [("@#{Internal.segment(api['lens'])}" if api['lens']),
-                  (Transforms.path(transform) unless transform.nil? || transform == '')].compact.join(',')
-      url += "/#{selector}" unless selector.empty?
+      EXTERNAL_ID_PREFIX + Internal.component(external)
+    end
 
-      claims = api['viewerClaims']
-      if !claims.nil? && (!claims.is_a?(Hash) || (claims.key?('ageConfirmed') && ![true, false].include?(claims['ageConfirmed'])))
-        raise Internal.invalid('Invalid viewerClaims')
+    # Appends a resource, its `@lens` and transform selector, and the viewer claims to an asset URL
+    # (public or signed). Without a resource the URL stays the asset URL, which takes no selector.
+    def append_location(url, api)
+      resource = api['resource']
+      selected = !api['lens'].nil? || !api['transform'].nil?
+      if resource.nil?
+        raise Internal.invalid('A lens or transform needs a resource, such as rendered') if selected
+      else
+        raise Internal.invalid("resource must be one of #{RESOURCES.join(', ')}") unless RESOURCE_PATHS.key?(resource)
+        if Internal::UNSELECTABLE_CDN_RESOURCES.include?(resource) && selected
+          raise Internal.invalid("The #{resource} resource takes no lens or transform")
+        end
+
+        url = "#{url}/#{RESOURCE_PATHS.fetch(resource)}"
+        transform = api['transform']
+        selector = [("@#{Internal.segment(api['lens'])}" if api['lens']),
+                    (Transforms.path(transform) unless transform.nil? || transform == '')].compact.join(',')
+        url += "/#{selector}" unless selector.empty?
+      end
+      "#{url}#{viewer_claims_query(api['viewerClaims'])}"
+    end
+
+    # Checks sign_asset_url's own options as the API does, then the location, before anything is sent.
+    def check_signing(api)
+      expires = api.fetch('expiresIn', DEFAULT_SIGNED_URL_EXPIRES_IN)
+      unless expires.is_a?(Integer) && expires.between?(1, MAX_SIGNED_URL_EXPIRES_IN)
+        raise Internal.invalid("expires_in must be a whole number of seconds from 1 to #{MAX_SIGNED_URL_EXPIRES_IN}")
       end
+      raise Internal.invalid('original must be true or false') unless [true, false].include?(api.fetch('original', false))
+
+      asset_segment(api)
+      append_location('', api)
+    end
+
+    # The `?viewerClaims=` query of a URL with these claims: the region, and `ageConfirmed` only when
+    # true. The defaults are left out, so default URLs stay cacheable.
+    def viewer_claims_query(claims)
+      return '' if claims.nil?
 
-      query = []
-      query << "viewerClaims=#{URI.encode_www_form_component(JSON.generate(ordered_claims(claims)))}" if claims
-      query.empty? ? url : "#{url}?#{query.join('&')}"
+      unless claims.is_a?(Hash) && (claims.keys - %w[region ageConfirmed]).empty? &&
+             (!claims.key?('region') || VIEWER_COUNTRIES.include?(claims['region'])) &&
+             (!claims.key?('ageConfirmed') || [true, false].include?(claims['ageConfirmed']))
+        raise Internal.invalid('Invalid viewer_claims: region is an ISO 3166-1 alpha-2 country and age_confirmed a boolean')
+      end
+
+      sent = {}
+      sent['region'] = claims['region'] if claims.key?('region')
+      sent['ageConfirmed'] = true if claims['ageConfirmed'] == true
+      sent.empty? ? '' : "?viewerClaims=#{URI.encode_www_form_component(JSON.generate(sent))}"
+    end
+
+    # An asset URL without its query, and the viewer claims it carried, if any.
+    def split_asset_url(url)
+      raise Internal.invalid('url must be an absolute asset URL') unless url.is_a?(String) && url.match?(%r{\Ahttps?://[^/?#]+/}i)
+
+      path, query = url.split('#', 2).first.split('?', 2)
+      raw = URI.decode_www_form(query.to_s).to_h['viewerClaims']
+      claims = begin
+        raw && JSON.parse(raw)
+      rescue JSON::ParserError
+        raise Internal.invalid("The asset URL's viewerClaims are not JSON")
+      end
+      [path.sub(%r{/+\z}, ''), claims]
     end
 
-    # Viewer claims in the order the other SDKs send them, so equal claims build equal CDN URLs.
-    def ordered_claims(claims)
-      known = %w[region ageConfirmed].select { |key| claims.key?(key) }.to_h { |key| [key, claims[key]] }
-      known.merge(claims.except(*known.keys))
+    def asset_info?(info)
+      info.is_a?(Hash) && info['id'].is_a?(String) && info['projectId'].is_a?(String) && info['type'].is_a?(String) &&
+        info['content'].is_a?(Hash) && %w[available age-restricted unavailable].include?(info['availability'])
     end
   end
 end

data/lib/calmlens/error_codes.rb

@@ -5,63 +5,63 @@
 module CalmLens
   # Error codes the CalmLens API returns, for comparing with {Error#code}.
   module ErrorCodes
-    INVALID_VIEWER_CLAIMS = 'viewer/invalid-claims'
+    INVALID_VIEWER_CLAIMS = 'viewer-claims/invalid'
     AGE_CONFIRMATION_REQUIRED = 'viewer/age-confirmation-required'
-    INVALID_VIEWER_REGION = 'viewer/invalid-region'
+    INVALID_VIEWER_REGION = 'viewer-region/invalid'
     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'
+    SIGNED_URL_ORIGINAL_NOT_GRANTED = 'signed-url/original-not-granted'
+    INVALID_REQUEST = 'validation/invalid-request'
     INVALID_TYPE = 'validation/invalid-type'
     TOO_SMALL = 'validation/too-small'
     TOO_BIG = 'validation/too-big'
     INVALID_FORMAT = 'validation/invalid-format'
     INVALID_VALUE = 'validation/invalid-value'
     UNKNOWN_FIELD = 'validation/unknown-field'
-    UNSUPPORTED_CONTENT_TYPE = 'validation/unsupported-content-type'
-    INVALID_FILTER = 'validation/invalid-filter'
-    INVALID_ORDERING_FIELD = 'validation/invalid-ordering-field'
-    ROUTE_NOT_FOUND = 'misc/route-not-found'
-    INTERNAL_ERROR = 'misc/internal-error'
+    UNSUPPORTED_CONTENT_TYPE = 'request/unsupported-content-type'
+    INVALID_FILTER = 'filter/invalid'
+    UNSUPPORTED_ORDERING_FIELD = 'ordering/unsupported-field'
+    ROUTE_NOT_FOUND = 'request/route-not-found'
+    INTERNAL_ERROR = 'server/internal-error'
     UNAUTHENTICATED = 'auth/unauthenticated'
-    TOKEN_EXPIRED = 'auth/token-expired'
-    INVALID_TOKEN = 'auth/invalid-token'
+    TOKEN_EXPIRED = 'session-token/expired'
+    INVALID_TOKEN = 'session-token/invalid'
     SEARCH_UNAVAILABLE = 'search/unavailable'
-    INVALID_TRANSFORM = 'asset/invalid-transform'
-    INVALID_TRANSFORM_OPTIONS = 'asset/invalid-transform-options'
-    REMOTE_URL_REDIRECT_LIMIT = 'asset/remote-url-redirect-limit'
-    COPYRIGHT_CONTENT_HELD = 'copyright/content-held'
-    DOWNLOAD_PERMISSION_REQUIRED = 'asset/api-key-missing-permission'
-    INVALID_CURSOR = 'validation/invalid-cursor'
-    MISSING_TOKEN = 'auth/missing-token'
-    INVALID_API_KEY = 'auth/invalid-api-key'
-    API_KEY_PROJECT_MISMATCH = 'auth/project-mismatch'
-    API_KEY_NOT_ACCEPTED = 'auth/api-key-not-accepted'
+    INVALID_TRANSFORM = 'transform/invalid'
+    INVALID_TRANSFORM_OPTIONS = 'transform-options/invalid'
+    REMOTE_URL_TOO_MANY_REDIRECTS = 'remote-url/too-many-redirects'
+    INVALID_CURSOR = 'cursor/invalid'
+    MISSING_API_KEY = 'api-key/missing'
+    INVALID_API_KEY = 'api-key/invalid'
+    API_KEY_PROJECT_MISMATCH = 'api-key/project-mismatch'
+    API_KEY_NOT_ACCEPTED = 'api-key/not-accepted'
     PERMISSION_DENIED = 'auth/permission-denied'
-    FILE_TOO_LARGE = 'upload/file-too-large'
-    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'
-    INVALID_UPLOAD_PAYLOAD = 'upload/invalid-payload'
+    UPLOAD_TOO_LARGE = 'upload/too-large'
+    DOCUMENT_TOO_MANY_ITEMS = 'document/too-many-items'
+    INVALID_IMAGE = 'image/invalid'
+    IMAGE_TOO_LARGE = 'image/too-large'
+    FREE_UPLOADS_EXHAUSTED = 'usage/free-uploads-exhausted'
+    UPLOADS_PAUSED = 'usage/uploads-paused'
+    UNSUPPORTED_UPLOAD_TYPE = 'upload/unsupported-type'
+    INVALID_UPLOAD_PAYLOAD = 'upload-payload/invalid'
     USE_UPLOAD_PART = 'upload/use-upload-part'
     UPLOAD_NOT_OPEN = 'upload/not-open'
-    INVALID_UPLOAD_PART_NUMBER = 'upload/invalid-part-number'
+    INVALID_UPLOAD_PART_NUMBER = 'upload-part/invalid-number'
     UPLOAD_MISSING = 'upload/missing'
     UPLOAD_SIZE_MISMATCH = 'upload/size-mismatch'
     INVALID_IDEMPOTENCY_KEY = 'idempotency/invalid-key'
     IDEMPOTENCY_KEY_REUSED = 'idempotency/key-reused'
     IDEMPOTENT_REQUEST_IN_PROGRESS = 'idempotency/request-in-progress'
+    NO_RENDERED_VERSION = 'asset/no-rendered-version'
     ASSET_NOT_FOUND = 'asset/not-found'
     PROJECT_NOT_FOUND = 'project/not-found'
+    ASSET_CHILD_NOT_DELETABLE = 'asset/child-not-deletable'
     ASSET_REVIEW_CHANGED = 'asset/review-changed'
     ASSET_REVIEW_NOTE_REQUIRED = 'asset/review-note-required'
     ASSET_UPDATE_FAILED = 'asset/update-failed'
-    ASSET_SAFETY_HELD = 'asset/safety-held'
+    ASSET_HELD = 'asset/held'
     ASSET_PROCESSING = 'asset/processing'
     ASSET_DECISION_NOT_ALLOWED = 'asset/decision-not-allowed'
     ASSET_DECISION_UNCHANGED = 'asset/decision-unchanged'
@@ -71,18 +71,19 @@ module CalmLens
     ASSET_NOT_DECIDED = 'asset/not-decided'
     ASSET_POLICY_CHANGED = 'asset/policy-changed'
     ASSET_REVIEWED = 'asset/reviewed'
-    SUPPORT_TICKET_NOT_FOUND = 'support/ticket-not-found'
+    SUPPORT_TICKET_NOT_FOUND = 'support-ticket/not-found'
     DUPLICATE_EXTERNAL_ID = 'asset/duplicate-external-id'
     FOLDER_NOT_FOUND = 'folder/not-found'
     DUPLICATE_FOLDER_NAME = 'folder/duplicate-name'
     FOLDER_NOT_EMPTY = 'folder/not-empty'
     FOLDER_PARENT_CYCLE = 'folder/parent-cycle'
-    LENS_VERSION_CONFLICT = 'lens/version-conflict'
+    LENS_NOT_FOUND = 'lens/not-found'
+    LENS_IDENTIFIER_TAKEN = 'lens/identifier-taken'
     LENS_IDENTIFIER_RESERVED = 'lens/identifier-reserved'
     HASH_LIST_NOT_FOUND = 'hash-list/not-found'
-    HASH_LIST_ENTRY_NOT_FOUND = 'hash-list/entry-not-found'
+    HASH_LIST_ENTRY_NOT_FOUND = 'hash-list-entry/not-found'
     HASH_LIST_LIMIT_REACHED = 'hash-list/limit-reached'
-    HASH_LIST_ENTRY_LIMIT_REACHED = 'hash-list/entry-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'
@@ -96,18 +97,16 @@ module CalmLens
     UPLOAD_PRESET_NOT_FOUND = 'upload-preset/not-found'
     UPLOAD_PRESET_DISABLED = 'upload-preset/disabled'
     UPLOAD_PRESET_TOKEN_REQUIRED = 'upload-preset/token-required'
-    REMOTE_URL_NOT_ALLOWED = 'upload/remote-url-not-allowed'
-    WEBSITE_RATE_LIMIT_EXCEEDED = 'upload/website-rate-limit-exceeded'
-    UPLOAD_PRESET_CONTENT_TYPE_NOT_ALLOWED = 'upload-preset/content-type-not-allowed'
-    UPLOAD_PRESET_TOO_LARGE = 'upload-preset/too-large'
+    REMOTE_URL_NOT_ALLOWED = 'remote-url/not-allowed'
+    WEBSITE_RATE_LIMIT_REACHED = 'upload/website-rate-limit-reached'
     UPLOAD_PRESET_DAILY_LIMIT_REACHED = 'upload-preset/daily-limit-reached'
     UPLOAD_PRESET_ORIGIN_NOT_ALLOWED = 'upload-preset/origin-not-allowed'
     UPLOAD_PRESET_FIELD_NOT_ALLOWED = 'upload-preset/field-not-allowed'
     UPLOAD_TOKEN_INVALID = 'upload-token/invalid'
     UPLOAD_TOKEN_EXPIRED = 'upload-token/expired'
     UPLOAD_TOKEN_USED = 'upload-token/used'
-    INVALID_REMOTE_URL = 'asset/invalid-remote-url'
-    REMOTE_URL_UNAVAILABLE = 'asset/remote-url-unavailable'
+    INVALID_REMOTE_URL = 'remote-url/invalid'
+    REMOTE_URL_UNAVAILABLE = 'remote-url/unavailable'
     APPEAL_NOT_FOUND = 'appeal/not-found'
     APPEAL_JUDGMENT_NOT_FOUND = 'appeal/judgment-not-found'
     APPEAL_ASSET_NOT_FOUND = 'appeal/asset-not-found'
@@ -115,68 +114,67 @@ module CalmLens
     APPEAL_ALREADY_REVIEWED = 'appeal/already-reviewed'
     APPEAL_DECISION_CHANGED = 'appeal/decision-changed'
     APPEAL_INVALID_ACTION = 'appeal/invalid-action'
-    APPEAL_SAFETY_HELD = 'appeal/safety-held'
     APPEAL_CONTENT_UNAVAILABLE = 'appeal/content-unavailable'
 
     # The HTTP status the API returns with each code.
     STATUSES = {
-      'viewer/invalid-claims' => 400,
+      'viewer-claims/invalid' => 400,
       'viewer/age-confirmation-required' => 403,
-      'viewer/invalid-region' => 400,
+      'viewer-region/invalid' => 400,
       'viewer/region-required' => 403,
       'asset/regional-evidence-required' => 403,
       'signed-url/expired' => 403,
       'signed-url/invalid' => 403,
+      'signed-url/original-not-granted' => 403,
+      'validation/invalid-request' => 400,
       'validation/invalid-type' => 400,
       'validation/too-small' => 400,
       'validation/too-big' => 400,
       'validation/invalid-format' => 400,
       'validation/invalid-value' => 400,
       'validation/unknown-field' => 400,
-      'validation/unsupported-content-type' => 415,
-      'validation/invalid-filter' => 400,
-      'validation/invalid-ordering-field' => 400,
-      'misc/route-not-found' => 404,
-      'misc/internal-error' => 500,
+      'request/unsupported-content-type' => 415,
+      'filter/invalid' => 400,
+      'ordering/unsupported-field' => 400,
+      'request/route-not-found' => 404,
+      'server/internal-error' => 500,
       'auth/unauthenticated' => 401,
-      'auth/token-expired' => 401,
-      'auth/invalid-token' => 401,
+      'session-token/expired' => 401,
+      'session-token/invalid' => 401,
       'search/unavailable' => 503,
-      'asset/invalid-transform' => 400,
-      'asset/invalid-transform-options' => 400,
-      'asset/remote-url-redirect-limit' => 400,
-      'copyright/content-held' => 409,
-      'asset/api-key-missing-permission' => 403,
-      'validation/invalid-cursor' => 400,
-      'auth/missing-token' => 401,
-      'auth/invalid-api-key' => 401,
-      'auth/project-mismatch' => 403,
-      'auth/api-key-not-accepted' => 403,
+      'transform/invalid' => 400,
+      'transform-options/invalid' => 400,
+      'remote-url/too-many-redirects' => 400,
+      'cursor/invalid' => 400,
+      'api-key/missing' => 401,
+      'api-key/invalid' => 401,
+      'api-key/project-mismatch' => 403,
+      'api-key/not-accepted' => 403,
       'auth/permission-denied' => 403,
-      'upload/file-too-large' => 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,
-      'upload/invalid-payload' => 400,
+      'upload/too-large' => 413,
+      'document/too-many-items' => 422,
+      'image/invalid' => 422,
+      'image/too-large' => 422,
+      'usage/free-uploads-exhausted' => 403,
+      'usage/uploads-paused' => 402,
+      'upload/unsupported-type' => 415,
+      'upload-payload/invalid' => 400,
       'upload/use-upload-part' => 409,
       'upload/not-open' => 409,
-      'upload/invalid-part-number' => 409,
+      'upload-part/invalid-number' => 409,
       'upload/missing' => 409,
       'upload/size-mismatch' => 400,
       'idempotency/invalid-key' => 400,
       'idempotency/key-reused' => 409,
       'idempotency/request-in-progress' => 409,
+      'asset/no-rendered-version' => 404,
       'asset/not-found' => 404,
       'project/not-found' => 404,
+      'asset/child-not-deletable' => 409,
       'asset/review-changed' => 409,
       'asset/review-note-required' => 400,
       'asset/update-failed' => 500,
-      'asset/safety-held' => 423,
+      'asset/held' => 423,
       'asset/processing' => 409,
       'asset/decision-not-allowed' => 409,
       'asset/decision-unchanged' => 409,
@@ -186,18 +184,19 @@ module CalmLens
       'asset/not-decided' => 409,
       'asset/policy-changed' => 409,
       'asset/reviewed' => 409,
-      'support/ticket-not-found' => 404,
+      'support-ticket/not-found' => 404,
       'asset/duplicate-external-id' => 409,
       'folder/not-found' => 404,
       'folder/duplicate-name' => 409,
       'folder/not-empty' => 409,
       'folder/parent-cycle' => 409,
-      'lens/version-conflict' => 409,
+      'lens/not-found' => 404,
+      'lens/identifier-taken' => 409,
       'lens/identifier-reserved' => 409,
       'hash-list/not-found' => 404,
-      'hash-list/entry-not-found' => 404,
+      'hash-list-entry/not-found' => 404,
       'hash-list/limit-reached' => 409,
-      'hash-list/entry-limit-reached' => 409,
+      'hash-list-entry/limit-reached' => 409,
       'hash-list/asset-not-hashed' => 409,
       'policy/not-found' => 404,
       'policy/revision-conflict' => 409,
@@ -211,18 +210,16 @@ module CalmLens
       'upload-preset/not-found' => 404,
       'upload-preset/disabled' => 403,
       'upload-preset/token-required' => 401,
-      'upload/remote-url-not-allowed' => 403,
-      'upload/website-rate-limit-exceeded' => 429,
-      'upload-preset/content-type-not-allowed' => 415,
-      'upload-preset/too-large' => 413,
+      'remote-url/not-allowed' => 403,
+      'upload/website-rate-limit-reached' => 429,
       'upload-preset/daily-limit-reached' => 429,
       'upload-preset/origin-not-allowed' => 403,
       'upload-preset/field-not-allowed' => 400,
       'upload-token/invalid' => 401,
       'upload-token/expired' => 401,
       'upload-token/used' => 409,
-      'asset/invalid-remote-url' => 400,
-      'asset/remote-url-unavailable' => 422,
+      'remote-url/invalid' => 400,
+      'remote-url/unavailable' => 422,
       'appeal/not-found' => 404,
       'appeal/judgment-not-found' => 404,
       'appeal/asset-not-found' => 404,
@@ -230,7 +227,6 @@ module CalmLens
       'appeal/already-reviewed' => 409,
       'appeal/decision-changed' => 409,
       'appeal/invalid-action' => 400,
-      'appeal/safety-held' => 409,
       'appeal/content-unavailable' => 409,
     }.freeze
   end

data/lib/calmlens/errors.rb

@@ -70,12 +70,12 @@ module CalmLens
     RETRYABLE_CODES = [SdkErrorCodes::TRANSPORT_ERROR, SdkErrorCodes::TIMEOUT,
                        ErrorCodes::IDEMPOTENT_REQUEST_IN_PROGRESS].freeze
     # HTTP statuses that may succeed when the same request is repeated.
-    RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
     private_constant :RETRYABLE_CODES, :RETRYABLE_STATUSES
 
     # @return [Boolean] true when repeating the same request may succeed: connection failures
     #   (`sdk/transport-error`), timeouts (`sdk/timeout`, including {Assets#wait_for_decision}),
-    #   `idempotency/request-in-progress`, throttling (429) and 502/503/504. Everything else,
+    #   `idempotency/request-in-progress`, throttling (429), 500, 502, 503 and 504. Everything else,
     #   including other 5xx statuses, is false. Repeat a write only with the same idempotency key.
     def retryable?
       RETRYABLE_CODES.include?(code) || RETRYABLE_STATUSES.include?(status)