calmlens 0.20.0 → 0.22.0

data/lib/calmlens/errors.rb

@@ -61,6 +61,15 @@ module CalmLens
       Error.parse_retry_after(headers['retry-after'])
     end
 
+    # @return [Boolean] true when the SDK raised this error itself, with no HTTP response: before
+    #   sending (an invalid argument or option, or content it checks first, such as
+    #   `upload/unsupported-type`), or because no response arrived (a timeout or a connection
+    #   failure). The code is the one the API would use; `status` and `request_id` are nil, so
+    #   branch on `code`.
+    def local?
+      status.nil?
+    end
+
     # @return [Boolean] true when the resource does not exist.
     def not_found?
       status == 404 || code.end_with?('/not-found')
@@ -70,12 +79,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)

data/lib/calmlens/events.rb

@@ -8,11 +8,17 @@ module CalmLens
 
     # Lists events after a cursor, oldest first. Without `cursor`, returns no events and a
     # `nextCursor` for the current time: save it, then pass each response's `nextCursor` as `cursor`.
+    # `types` and `asset_id` narrow the feed to some event types or one asset's events. A cursor
+    # belongs to the filters it was issued with, so pass the same ones with each `cursor`.
     # @option options [String] :cursor the `nextCursor` of a previous response
     # @option options [Integer] :page_size 1 to 100, default 50
+    # @option options [Array<String>] :types event types to list, such as `asset.blocked`
+    # @option options [String] :asset_id list only this asset's events
     # @return [Hash] `{'items', 'nextCursor', 'hasMore'}`; `nextCursor` is never nil
     def list(options = {})
-      call(options, __method__) { |api, request| request('GET', project('events'), query: api, request_options: request) }
+      call(options, __method__) do |api, request|
+        request('GET', project('events'), query: feed_query(api), request_options: request)
+      end
     end
 
     # Iterates pages from `cursor` until `hasMore` is false. Persist each page's `nextCursor` once its
@@ -48,5 +54,48 @@ module CalmLens
 
       each_page(options) { |page| page['items'].each(&block) }
     end
+
+    private
+
+    # The API takes the types as one comma-separated value; an empty list filters nothing.
+    def feed_query(api)
+      types = api['types']
+      return api unless api.key?('types')
+      raise Internal.invalid('types must be an Array of event type Strings') unless types.is_a?(Array) && types.all?(String)
+
+      api.merge('types' => types.empty? ? nil : types.join(','))
+    end
+  end
+
+  # Reads an event's facts: an {Events#list} item, a webhook delivery body or a {WebhookEvent}.
+  # {CalmLens.get_event_fact} and {CalmLens.get_event_facts} call it.
+  module EventFacts
+    module_function
+
+    # The value of one of an event's facts, by key, such as `'flagged-categories'`, or nil when the
+    # event doesn't carry it. A key the event repeats gives its first value. The fact's `url`, when
+    # it has one, is on the fact in the event's `facts`.
+    # @param event [WebhookEvent, Hash] a parsed delivery, or an event or delivery body with string keys
+    # @param key [String]
+    # @return [Object, nil]
+    def value(event, key)
+      found = facts_of(event).find { |fact| fact['key'] == key }
+      found && found['value']
+    end
+
+    # An event's facts as a Hash of values by key, such as `{ 'flagged-categories' => ['hate'] }`.
+    # A key the event repeats keeps its first value, as {.value} reads it.
+    # @param event [WebhookEvent, Hash] a parsed delivery, or an event or delivery body with string keys
+    # @return [Hash{String => Object}]
+    def values(event)
+      facts_of(event).each_with_object({}) { |fact, found| found[fact['key']] = fact['value'] unless found.key?(fact['key']) }
+    end
+
+    # The well-formed facts of an event, in order.
+    def facts_of(event)
+      facts = event.is_a?(Hash) ? event['facts'] : event.facts
+      facts.is_a?(Array) ? facts.select { |fact| fact.is_a?(Hash) && fact['key'].is_a?(String) } : []
+    end
+    private_class_method :facts_of
   end
 end

data/lib/calmlens/folders.rb

@@ -6,24 +6,29 @@ module CalmLens
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
     OPERATIONS = 'folders'
 
-    # Lists one page of child folders, sorted by name unless `ordering` says otherwise.
+    # Lists one page of child folders, sorted by name unless `sort` says otherwise.
     # @option options [String] :parent_id list this folder's children; omit for the project root
     # @option options [String] :cursor the previous page's `nextCursor`
     # @option options [Integer] :page_size 1 to 100, default 50
-    # @option options [Array<Hash>] :ordering one `{field: 'name' | 'createdAt', direction: 'asc' | 'desc'}`
+    # @option options [String] :sort `name` (the default) or `createdAt`, descending when prefixed with `-`
     # @option options [String] :search only children whose name contains it
-    # @return [Hash] a cursor page (items, nextCursor, hasMore, pageSize, ordering) with ancestors.
+    # @return [Hash] a cursor page (items, nextCursor, hasMore) with ancestors.
     def list(options = {})
       call(options, __method__) do |api, request|
-        response = request('GET', project('folders'), query: api, request_options: request)
-        valid = response.is_a?(Hash) && response['items'].is_a?(Array) && response['ancestors'].is_a?(Array) &&
-                [true, false].include?(response['hasMore'])
-        raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Invalid folder page') unless valid
-
-        response
+        cursor_page(request('GET', project('folders'), query: api, request_options: request), 'folder')
       end
     end
 
+    # Iterates every child folder of `parent_id` (or the project root), fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam folder [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_item(options, __method__, method(:list), &block)
+    end
+
     # @option options [String] :name
     # @option options [String, nil] :parent_id
     # @return [Hash] the folder

data/lib/calmlens/hash_lists.rb

@@ -8,20 +8,28 @@ module CalmLens
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
     OPERATIONS = 'hashLists'
 
-    # Lists one page of the project's hash lists, newest first.
+    # Lists one page of the project's hash lists, newest first unless `sort` says otherwise.
     # @option options [String] :cursor the previous page's `nextCursor`
     # @option options [Integer] :page_size 1 to 100, default 50
-    # @return [Hash] a cursor page: items, nextCursor, hasMore, pageSize and ordering.
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`; `-createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
     def list(options = {})
       call(options, __method__) do |api, request|
-        response = request('GET', project('hash-lists'), query: api, request_options: request)
-        valid = response.is_a?(Hash) && response['items'].is_a?(Array)
-        raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Invalid hash list page') unless valid
-
-        response
+        cursor_page(request('GET', project('hash-lists'), query: api, request_options: request), 'hash list')
       end
     end
 
+    # Iterates every hash list, fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam hash_list [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_item(options, __method__, method(:list), &block)
+    end
+
     # @option options [String] :hash_list_id
     # @return [Hash] the hash list
     def retrieve(options)
@@ -58,17 +66,29 @@ module CalmLens
       end
     end
 
-    # Lists one page of a list's entries, newest first.
+    # Lists one page of a list's entries, newest first unless `sort` says otherwise.
     # @option options [String] :hash_list_id
     # @option options [String] :cursor the previous page's `nextCursor`
     # @option options [Integer] :page_size 1 to 100, default 50
-    # @return [Hash] a cursor page: items, nextCursor, hasMore, pageSize and ordering.
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`; `-createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
     def list_entries(options)
       call(options, __method__) do |api, request|
         request('GET', "#{list_path(api)}/entries", query: without(api, 'hashListId'), request_options: request)
       end
     end
 
+    # Iterates every entry of a list, fetching pages as needed.
+    # @param options [Hash] the options of {#list_entries}; `cursor` sets the starting position.
+    # @yieldparam entry [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each_entry(options, &block)
+      return enum_for(:each_entry, options) unless block
+
+      each_item(options, __method__, method(:list_entries), &block)
+    end
+
     # Adds a PDQ hash, or an image asset's hash; a hash already in the list returns its entry.
     # @option options [String] :hash_list_id
     # @option options [String] :hash 64 hexadecimal characters; send this or `asset_id`

data/lib/calmlens/internal.rb

@@ -13,6 +13,9 @@ module CalmLens
     # ASCII characters without a space at either end) and answers `idempotency/invalid-key`.
     IDEMPOTENCY_KEY = /\A[^\r\n\0]+\z/
     HEADER_VALUE = /\A[^\r\n\0]*\z/
+    # The CDN resources that take no lens or transform: the exact upload, the adaptive stream, the embed page,
+    # the public placeholder and the display info.
+    UNSELECTABLE_CDN_RESOURCES = %w[original hls embed placeholder info].freeze
 
     module_function
 
@@ -103,10 +106,12 @@ module CalmLens
       raise invalid('Identifier is required') if text.empty?
       raise invalid('Identifier cannot be "." or ".."') if %w[. ..].include?(text)
 
-      # Like JavaScript's encodeURIComponent.
-      text.encode(Encoding::UTF_8).b.gsub(/[^A-Za-z0-9\-_.!~*'()]/n) { |byte| format('%%%02X', byte.ord) }
+      component(text)
     end
 
+    # Percent-encodes text like JavaScript's encodeURIComponent.
+    def component(text) = text.encode(Encoding::UTF_8).b.gsub(/[^A-Za-z0-9\-_.!~*'()]/n) { |byte| format('%%%02X', byte.ord) }
+
     # Splits an absolute URL into its parsed origin and its raw request target. Only the origin is
     # parsed, so the request target is sent exactly as the SDK built it.
     # @return [Array(URI::Generic, String)]
@@ -133,24 +138,9 @@ module CalmLens
       end
     end
 
-    # Encodes query values the way the API's parser expects: strings as-is, everything else as
-    # JSON, and ordering as `ordering[i][field]` pairs.
+    # Encodes query values the way the API's parser expects: strings as-is, everything else as JSON.
     def query(params)
-      encoded = {}
-      params.each do |key, value|
-        next if value.nil?
-
-        if key == 'ordering' && value.is_a?(Array)
-          value.each_with_index do |order, index|
-            raise invalid('Each ordering entry must be a Hash') unless order.is_a?(Hash)
-
-            order.each { |name, item| encoded["ordering[#{index}][#{name}]"] = item.to_s }
-          end
-        else
-          encoded[key] = value.is_a?(String) ? value : JSON.generate(value)
-        end
-      end
-      encoded
+      params.compact.transform_values { |value| value.is_a?(String) ? value : JSON.generate(value) }
     end
   end
   private_constant :Internal

data/lib/calmlens/lenses.rb

@@ -1,20 +1,93 @@
 # frozen_string_literal: true
 
 module CalmLens
-  # Lens definitions, cached per client. Used through {ServerClient#ensure_lenses} and {ServerClient#ensure_lens}.
-  # @api private
+  # The project's lenses: named image transforms the CDN applies at `/@<identifier>`. The CDN serves
+  # files made with each lens's current definition. Reach it through {ServerClient#lenses};
+  # {ServerClient#ensure_lenses} creates or changes lenses by identifier, for applications that
+  # declare theirs in code.
   class Lenses < Resource
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
-    OPERATIONS = nil
+    OPERATIONS = 'lenses'
+
+    # Lists one page of the project's lenses, newest first unless `sort` says otherwise.
+    # @option options [String] :cursor the previous page's `nextCursor`
+    # @option options [Integer] :page_size 1 to 100, default 50
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`; `-createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
+    def list(options = {})
+      call(options, __method__) do |api, request|
+        cursor_page(request('GET', project('lenses'), query: api, request_options: request), 'lens')
+      end
+    end
+
+    # Iterates every lens of the project, fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam lens [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_item(options, __method__, method(:list), &block)
+    end
+
+    # Creates a lens; its identifier must be new to the project (`lens/identifier-taken` otherwise).
+    # @option options [String] :identifier
+    # @option options [String] :name
+    # @option options [String] :type `image`
+    # @option options [Boolean] :active whether the CDN serves it
+    # @option options [String, nil] :description
+    # @option options [Hash, String, nil] :transform
+    # @return [Hash] the lens
+    def create(options)
+      call(options, __method__) do |api, request|
+        lens = request('POST', project('lenses'), body: api, request_options: request)
+        @session.forget_lenses { |cached| cached['identifier'] == lens['identifier'] } if lens.is_a?(Hash)
+        lens
+      end
+    end
+
+    # @option options [String] :lens_id
+    # @return [Hash] the lens
+    def retrieve(options)
+      call(options, __method__) { |api, request| request('GET', lens_path(api), request_options: request) }
+    end
+
+    # Changes a lens's name, description, type, transform or whether the CDN serves it.
+    # @option options [String] :lens_id
+    # @return [Hash] the lens
+    def update(options)
+      call(options, __method__) do |api, request|
+        lens = request('PATCH', lens_path(api), body: without(api, 'lensId'), request_options: request)
+        @session.forget_lenses { |cached| cached['id'] == lens['id'] } if lens.is_a?(Hash)
+        lens
+      end
+    end
+
+    # Deletes a lens; URLs that select it stop being served.
+    # @option options [String] :lens_id
+    # @return [nil]
+    def delete(options)
+      call(options, __method__) do |api, request|
+        request('DELETE', lens_path(api), request_options: request)
+        @session.forget_lenses { |cached| cached['id'] == api['lensId'] }
+        nil
+      end
+    end
 
     # Lens definitions are sent as given, nil fields included.
+    # @api private
     def ensure_lenses(options)
-      call(options, __method__, keep_nil: true) { |api, request| @session.ensure_lenses(api['lenses'], request) }
+      call(options, __method__, keep_nil: true, prefix: nil) { |api, request| @session.ensure_lenses(api['lenses'], request) }
     end
 
+    # @api private
     def ensure_lens(options)
-      call(options, __method__, keep_nil: true) { |api, request| @session.ensure_lenses([api], request).first }
+      call(options, __method__, keep_nil: true, prefix: nil) { |api, request| @session.ensure_lenses([api], request).first }
     end
+
+    private
+
+    def lens_path(api) = "/lenses/#{Internal.segment(api['lensId'])}"
   end
-  private_constant :Lenses
 end

data/lib/calmlens/option_keys.rb

@@ -9,71 +9,98 @@ module CalmLens
       'assets.batch' => %w[assetIds operation].freeze,
       'assets.classify' => %w[
         authorId content context description externalId externalUrl folderId isFinal metadata name part
-        processingOptions sizeInBytes totalSizeInBytes uploadPresetId url visibility
+        processingOptions sizeInBytes tags totalSizeInBytes uploadPresetId url visibility
       ].freeze,
       'assets.create' => %w[
         authorId content context description externalId externalUrl folderId isFinal metadata name part
-        processingOptions sizeInBytes totalSizeInBytes uploadPresetId url visibility
+        processingOptions sizeInBytes tags totalSizeInBytes uploadPresetId url visibility
       ].freeze,
-      'assets.createSignedUrl' => %w[assetId expiresInSeconds lens resource transform viewerClaims].freeze,
       'assets.decide' => %w[assetId confirmPurge decision note].freeze,
       'assets.delete' => %w[assetId].freeze,
-      'assets.deleteContent' => %w[assetId].freeze,
-      'assets.each' => %w[cursor filter folderId ordering pageSize].freeze,
-      'assets.eachChild' => %w[assetId cursor ordering pageSize].freeze,
+      'assets.each' => %w[cursor filter pageSize sort].freeze,
+      'assets.eachChild' => %w[assetId cursor pageSize sort].freeze,
+      'assets.eachTimelineSegment' => %w[assetId cursor pageSize].freeze,
       'assets.explain' => %w[assetId rerun].freeze,
-      'assets.list' => %w[cursor filter folderId ordering pageSize].freeze,
-      'assets.listChildren' => %w[assetId cursor ordering pageSize].freeze,
+      'assets.list' => %w[cursor filter pageSize sort].freeze,
+      'assets.listChildren' => %w[assetId cursor pageSize sort].freeze,
+      'assets.listTimeline' => %w[assetId cursor pageSize].freeze,
       'assets.move' => %w[assetId folderId].freeze,
+      'assets.removeContent' => %w[assetId].freeze,
       'assets.retrieve' => %w[assetId].freeze,
       'assets.retry' => %w[assetId].freeze,
-      'assets.search' => %w[limit mode query].freeze,
+      'assets.search' => %w[mode pageSize query].freeze,
       'assets.update' => %w[assetId description externalId externalUrl metadata name tags visibility].freeze,
-      'assets.uploadPart' => %w[assetId part queue].freeze,
-      'ensureLens' => %w[active description identifier name transform type version].freeze,
+      'assets.uploadPart' => %w[assetId part wait].freeze,
+      'cdn.signAssetUrl' => %w[
+        assetId expiresIn externalId lens original projectId resource transform viewerClaims
+      ].freeze,
+      'ensureLens' => %w[active description identifier name transform type].freeze,
       'ensureLenses' => %w[lenses].freeze,
-      'events.each' => %w[cursor pageSize].freeze,
-      'events.eachPage' => %w[cursor pageSize].freeze,
-      'events.list' => %w[cursor pageSize].freeze,
+      'events.each' => %w[assetId cursor pageSize types].freeze,
+      'events.eachPage' => %w[assetId cursor pageSize types].freeze,
+      'events.list' => %w[assetId cursor pageSize types].freeze,
       'folders.create' => %w[name parentId].freeze,
       'folders.delete' => %w[folderId].freeze,
-      'folders.list' => %w[cursor ordering pageSize parentId search].freeze,
+      'folders.each' => %w[cursor pageSize parentId search sort].freeze,
+      'folders.list' => %w[cursor pageSize parentId search sort].freeze,
       'folders.move' => %w[folderId parentId].freeze,
       'folders.retrieve' => %w[folderId].freeze,
       'folders.update' => %w[folderId name].freeze,
       'hashLists.addEntry' => %w[assetId hash hashListId label quality].freeze,
       'hashLists.create' => %w[action description name].freeze,
       'hashLists.delete' => %w[hashListId].freeze,
-      'hashLists.list' => %w[cursor ordering pageSize].freeze,
-      'hashLists.listEntries' => %w[cursor hashListId ordering pageSize].freeze,
+      'hashLists.each' => %w[cursor pageSize sort].freeze,
+      'hashLists.eachEntry' => %w[cursor hashListId pageSize sort].freeze,
+      'hashLists.list' => %w[cursor pageSize sort].freeze,
+      'hashLists.listEntries' => %w[cursor hashListId pageSize sort].freeze,
       'hashLists.removeEntry' => %w[entryId].freeze,
       'hashLists.retrieve' => %w[hashListId].freeze,
       'hashLists.update' => %w[action description hashListId name].freeze,
-      'policies.applyPreset' => %w[operation policyId presetVersion revision].freeze,
+      'lenses.create' => %w[active description identifier name transform type].freeze,
+      'lenses.delete' => %w[lensId].freeze,
+      'lenses.each' => %w[cursor pageSize sort].freeze,
+      'lenses.list' => %w[cursor pageSize sort].freeze,
+      'lenses.retrieve' => %w[lensId].freeze,
+      'lenses.update' => %w[active description lensId name transform type].freeze,
+      'metadataFields.delete' => %w[fieldId revision].freeze,
+      'metadataFields.ensure' => %w[fields revision].freeze,
+      'metadataFields.list' => %w[].freeze,
       'policies.assign' => %w[policyId].freeze,
       'policies.create' => %w[description name presetId settings].freeze,
       'policies.delete' => %w[policyId].freeze,
-      'policies.list' => %w[].freeze,
+      'policies.each' => %w[cursor pageSize sort].freeze,
+      'policies.list' => %w[cursor pageSize sort].freeze,
+      'policies.reset' => %w[policyId presetVersion revision].freeze,
       'policies.retrieve' => %w[policyId].freeze,
+      'policies.retrieveAssigned' => %w[].freeze,
       'policies.setAutomaticUpdates' => %w[enabled policyId presetVersion revision].freeze,
       'policies.update' => %w[description name policyId revision settings].freeze,
+      'policies.upgrade' => %w[policyId presetVersion revision].freeze,
+      'projectSettings.get' => %w[].freeze,
+      'projectSettings.update' => %w[revision searchIndexingBudgetUnits settings].freeze,
       'text.classify' => %w[
-        authorId context description externalId externalUrl folderId metadata name processingOptions text
+        authorId context description externalId externalUrl folderId metadata name processingOptions tags text
         uploadPresetId visibility
-      ].freeze
+      ].freeze,
+      'uploadPresets.delete' => %w[uploadPresetId].freeze,
+      'uploadPresets.each' => %w[cursor pageSize sort].freeze,
+      'uploadPresets.ensure' => %w[uploadPresets].freeze,
+      'uploadPresets.list' => %w[cursor pageSize sort].freeze
     }.freeze
 
     # The option keys each method sends as null when given nil; any other option given as nil
     # is left out, as the API refuses null for it.
     NULLABLE_OPTION_KEYS = {
       'assets.classify' => %w[
-        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+        authorId context description externalId folderId metadata processingOptions tags uploadPresetId
+        visibility
       ].freeze,
       'assets.create' => %w[
-        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+        authorId context description externalId folderId metadata processingOptions tags uploadPresetId
+        visibility
       ].freeze,
-      'assets.each' => %w[filter folderId].freeze,
-      'assets.list' => %w[filter folderId].freeze,
+      'assets.each' => %w[filter].freeze,
+      'assets.list' => %w[filter].freeze,
       'assets.move' => %w[folderId].freeze,
       'assets.update' => %w[description externalId externalUrl metadata tags visibility].freeze,
       'folders.create' => %w[parentId].freeze,
@@ -81,8 +108,11 @@ module CalmLens
       'hashLists.addEntry' => %w[label quality].freeze,
       'hashLists.create' => %w[description].freeze,
       'hashLists.update' => %w[description].freeze,
+      'lenses.create' => %w[description transform].freeze,
+      'lenses.update' => %w[description transform].freeze,
       'text.classify' => %w[
-        authorId context description externalId folderId metadata processingOptions uploadPresetId visibility
+        authorId context description externalId folderId metadata processingOptions tags uploadPresetId
+        visibility
       ].freeze
     }.freeze
   end

data/lib/calmlens/policies.rb

@@ -1,18 +1,34 @@
 # frozen_string_literal: true
 
 module CalmLens
-  # Moderation policies belong to the project's organisation and its projects share them. Every
+  # Moderation policies belong to the API key's organisation and its projects share them. Every
   # change sends the policy's `revision`, so a policy changed since is refused with
   # `policy/revision-conflict`. Through a project's key you can change only policies no other
-  # project uses or owns. Reach it through {ServerClient#policies}.
+  # project uses. Reach it through {ServerClient#policies}.
   class Policies < Resource
     # The prefix of this resource's operations in Internal::OPTION_KEYS.
     OPERATIONS = 'policies'
 
-    # Lists the organisation's policies, oldest first, and the ID of the one the project uses.
-    # @return [Hash] `policies` and `projectPolicyId`
+    # Lists one page of the organisation's policies, oldest first unless `sort` says otherwise.
+    # @option options [String] :cursor the previous page's `nextCursor`
+    # @option options [Integer] :page_size 1 to 100, default 50
+    # @option options [String] :sort `createdAt` and `id`, comma-separated, descending when prefixed
+    #   with `-`; `createdAt` by default
+    # @return [Hash] a cursor page: items, nextCursor and hasMore.
     def list(options = {})
-      call(options, __method__) { |_api, request| request('GET', project('policies'), request_options: request) }
+      call(options, __method__) do |api, request|
+        cursor_page(request('GET', '/policies', query: api, request_options: request), 'policy')
+      end
+    end
+
+    # Iterates every policy of the organisation, fetching pages as needed.
+    # @param options [Hash] the options of {#list}; `cursor` sets the starting position.
+    # @yieldparam policy [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_item(options, __method__, method(:list), &block)
     end
 
     # @option options [String] :policy_id
@@ -21,21 +37,28 @@ module CalmLens
       call(options, __method__) { |api, request| request('GET', policy_path(api), request_options: request) }
     end
 
+    # The policy the project moderates with.
+    # @return [Hash] the policy
+    def retrieve_assigned(options = {})
+      call(options, __method__) { |_api, request| request('GET', project('policy'), request_options: request) }
+    end
+
     # Creates a policy from `settings` (defining every category) with a `name`, or a copy of the
     # latest release of a built-in preset with `preset_id`. It moderates nothing until it is
     # assigned to a project or named on an upload preset.
     # @option options [String] :name required with `settings`; a preset copy defaults to its name
     # @option options [String] :description
-    # @option options [Hash] :settings
+    # @option options [Hash] :settings `categorySettings` with every category, each with its
+    #   `action`, `allowances` and `restrictions`
     # @option options [String] :preset_id `general-community`, `children-platform`, `education-support`
     #   or `wholesome-community`
     # @return [Hash] the policy
     def create(options)
-      call(options, __method__) { |api, request| request('POST', project('policies'), body: api, request_options: request) }
+      call(options, __method__) { |api, request| request('POST', '/policies', body: api, request_options: request) }
     end
 
     # Changes the name, description or settings (complete, defining every category); later
-    # moderation uses them. Saving a policy that follows automatic updates pins it as a copy.
+    # moderation uses them. Saving a `live` policy pins it.
     # @option options [String] :policy_id
     # @option options [Integer] :revision the policy's current revision
     # @option options [String] :name
@@ -48,22 +71,31 @@ module CalmLens
       end
     end
 
-    # Resets a preset copy to its pinned preset version, or updates an unchanged copy to the latest
-    # preset release.
+    # Restores the settings of the preset release a `pinned` or `copy` policy is pinned to.
+    # @option options [String] :policy_id
+    # @option options [Integer] :revision the policy's current revision
+    # @option options [Integer] :preset_version the pinned `preset.version` you reviewed
+    # @return [Hash] the policy
+    def reset(options)
+      call(options, __method__) do |api, request|
+        request('POST', "#{policy_path(api)}/reset", body: without(api, 'policyId'), request_options: request)
+      end
+    end
+
+    # Moves an unchanged `pinned` or `copy` policy to the latest release of its preset.
     # @option options [String] :policy_id
-    # @option options [String] :operation `reset` or `update`
     # @option options [Integer] :revision the policy's current revision
-    # @option options [Integer] :preset_version `preset.version` to reset, `preset.latestVersion` to update
+    # @option options [Integer] :preset_version the `preset.latestVersion` you reviewed
     # @return [Hash] the policy
-    def apply_preset(options)
+    def upgrade(options)
       call(options, __method__) do |api, request|
-        request('POST', "#{policy_path(api)}/preset", body: without(api, 'policyId'), request_options: request)
+        request('POST', "#{policy_path(api)}/upgrade", body: without(api, 'policyId'), request_options: request)
       end
     end
 
-    # Switches automatic updates on or off for the organisation's own preset policy. Switching on
-    # replaces the saved copy with the latest preset settings under the same ID; switching off pins
-    # the current preset version as a copy with unchanged settings.
+    # Switches automatic updates on (mode `live`) or off (mode `pinned`) for the organisation's own
+    # preset policy. Switching on replaces the saved settings with the latest preset settings under
+    # the same ID; switching off pins the current preset version with unchanged settings.
     # @option options [String] :policy_id
     # @option options [Boolean] :enabled
     # @option options [Integer] :revision the policy's current revision
@@ -95,6 +127,6 @@ module CalmLens
 
     private
 
-    def policy_path(api) = project("policies/#{Internal.segment(api['policyId'])}")
+    def policy_path(api) = "/policies/#{Internal.segment(api['policyId'])}"
   end
 end