calmlens 0.19.0 → 0.21.0

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
 
@@ -79,6 +82,16 @@ module CalmLens
       value.is_a?(Numeric) && value.real? && value.to_f.finite? && value.positive?
     end
 
+    # Whether the API accepts an upload of this MIME type: an image, audio, video, text, document or
+    # website type, not a container such as `application/octet-stream`. It refuses any other type
+    # with `upload/invalid-mime-type`.
+    def accepted_upload_mime_type?(type)
+      mime = type.to_s.split(';', 2).first.to_s.strip.downcase
+      return false if UPLOAD_MIME_REJECTED.include?(mime)
+
+      mime.start_with?(*UPLOAD_MIME_PREFIXES) || mime.end_with?(*UPLOAD_MIME_SUFFIXES) || UPLOAD_MIME_TYPES.include?(mime)
+    end
+
     # Fetches a required option.
     def required(options, key, code = SdkErrorCodes::INVALID_ARGUMENT)
       raise invalid("#{key} is required", code) unless options.key?(key)
@@ -93,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)]
@@ -123,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,19 +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__) { |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__) { |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,58 +9,102 @@ 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,
       '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,
       '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
+
+    # 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 tags uploadPresetId
+        visibility
+      ].freeze,
+      'assets.create' => %w[
+        authorId context description externalId folderId metadata processingOptions tags uploadPresetId
+        visibility
+      ].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,
+      'folders.move' => %w[parentId].freeze,
+      '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 tags uploadPresetId
+        visibility
+      ].freeze
+    }.freeze
   end
 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 project's 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

data/lib/calmlens/resource.rb

@@ -19,18 +19,25 @@ module CalmLens
     # beside a request's; Internal::OPTION_KEYS, generated from the API, has the rest.
     LOCAL_OPTION_KEYS = {
       'assets.waitForDecision' => %w[assetId timeout].freeze,
-      'cdn.getAssetUrl' => %w[assetIdentifier lens resource transform viewerClaims].freeze,
-      'cdn.serve' => %w[assetIdentifier init lens resource transform viewerClaims].freeze,
-      'uploadTokens.sign' => %w[expiresInSeconds externalId uploadPresetId].freeze
+      'cdn.getAssetUrl' => %w[assetId externalId lens projectId resource transform viewerClaims].freeze,
+      'cdn.serve' => %w[assetId externalId init lens projectId resource transform viewerClaims].freeze,
+      'uploadTokens.sign' => %w[expiresIn externalId uploadPresetId].freeze
     }.freeze
     private_constant :LOCAL_OPTION_KEYS
 
     # Runs a public method: splits options, and raises every argument problem as {InvalidArgumentError}.
     # `method` names the public method: an option it doesn't take, such as a misspelt one, raises
     # `sdk/invalid-argument` instead of being silently dropped.
-    def call(options, method)
-      check_option_keys(options, [self.class::OPERATIONS, Internal.camelize(method)].compact.join('.'))
+    # An option given as nil is left out, as if omitted, unless the API takes null for it
+    # (Internal::NULLABLE_OPTION_KEYS), such as `description: nil` to clear a description;
+    # `keep_nil: true` sends every option as given, as for a lens definition. `prefix` names the
+    # operation's resource, the resource's own unless the method belongs to the client itself.
+    def call(options, method, keep_nil: false, prefix: self.class::OPERATIONS)
+      operation = [prefix, Internal.camelize(method)].compact.join('.')
+      check_option_keys(options, operation)
       api, request = Internal.options(options)
+      nullable = Internal::NULLABLE_OPTION_KEYS.fetch(operation, [])
+      api = api.reject { |key, value| value.nil? && !nullable.include?(key) } unless keep_nil
       yield api, request
     rescue Error
       raise
@@ -78,6 +85,23 @@ module CalmLens
       end
     end
 
+    # A list's response, once it is a cursor page: a Hash with an `items` Array. `what` names the
+    # items in the `sdk/invalid-response` error otherwise.
+    def cursor_page(response, what)
+      return response if response.is_a?(Hash) && response['items'].is_a?(Array)
+
+      raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, "Invalid #{what} page")
+    end
+
+    # Iterates the items of every page `list` returns for `options`, from its `cursor`, yielding each
+    # to `block`. `method` names the public iterator, whose options are checked like the list's.
+    def each_item(options, method, list, &block)
+      api, request = call(options, method) { |*split| split }
+      listing = pages(api['cursor']) { |cursor| list.call(api.merge('cursor' => cursor, 'request_options' => request)) }
+      listing.each { |page| page['items'].each(&block) }
+      nil
+    end
+
     # Records a cursor an iteration sends, raising `sdk/invalid-response` (with `details['cursor']`)
     # when a page with more to follow hands back one it already sent, which would repeat pages forever.
     def new_cursor!(sent, cursor)